Semantic versioning

From APIDesign

(Difference between revisions)
Jump to: navigation, search
Line 1: Line 1:
[[Semantic versioning]] is a natural interpretation of [[dependencies]] as described in manifesto at [http://semver.org/ semver.org]. It is also a base for designing [[library|libraries]] with [[semantic versioning|few to many]] [[proximity]] between their [[ClientAPI]] and [[ProviderAPI]] sides.
[[Semantic versioning]] is a natural interpretation of [[dependencies]] as described in manifesto at [http://semver.org/ semver.org]. It is also a base for designing [[library|libraries]] with [[semantic versioning|few to many]] [[proximity]] between their [[ClientAPI]] and [[ProviderAPI]] sides.
-
There is also another proposal for [http://www.osgi.org/wiki/uploads/Links/SemanticVersioning.pdf semantic versioning] defined by [[OSGi]] guys. It is using [[range dependencies]] to distinguish between [[ClientAPI]] (always uses major dependencies range like 1.x to 2.0) and [[ProviderAPI]] (which is supposed to always depend on 1.x to 1.(x+1) micro range). This style of versioning opens the [[vendor library]] [[proximity]] category up to a bit more distant [[ProviderAPI|providers]]. If the [[OSGi]] [[semantic versioning]] is obeyed, one can use [[Final interface]] as a contract between [[ClientAPI|clients of your API]] and [[ProviderAPI|providers of your API]]. It is expected that in case there is an incompatible change in the [[Final interface]], you bump up the micro version.
+
This [[proximity]] is best explained by another [[semantic versioning]] [http://www.osgi.org/wiki/uploads/Links/SemanticVersioning.pdf proposal] defined by [[OSGi]] guys. It is using [[range dependencies]] to distinguish between [[ClientAPI]] (always uses major dependencies range like 1.x to 2.0) and [[ProviderAPI]] (which is supposed to always depend on 1.x to 1.(x+1) micro range). This style of versioning opens the [[vendor library]] [[proximity]] category up to a bit more distant [[ProviderAPI|providers]]. If the [[OSGi]] [[semantic versioning]] is obeyed, one can use [[Final interface]] as a contract between [[ClientAPI|clients of your API]] and [[ProviderAPI|providers of your API]]. It is expected that in case there is an incompatible change in the [[Final interface]], you bump up the micro version.
Althrough common design practise in [[OSGi]] world the drawbacks are obvious. Every change into the [[API]] renders all existing providers invalid (as the new version of library is out of their micro [[dependency]] range). With every such change all providers need to be rewritten. Should there be two providers written against different version of the [[API]] they are unlikely to co-exist together.
Althrough common design practise in [[OSGi]] world the drawbacks are obvious. Every change into the [[API]] renders all existing providers invalid (as the new version of library is out of their micro [[dependency]] range). With every such change all providers need to be rewritten. Should there be two providers written against different version of the [[API]] they are unlikely to co-exist together.
Due to these limitations I call this library style a '''few to many''' [[proximity]]. It is possible to have multiple [[ProviderAPI|providers]], but as they use micro range, there can never be as much providers as clients. In case you seek real '''many to many''' [[proximity]] consider using [[modular library]] design.
Due to these limitations I call this library style a '''few to many''' [[proximity]]. It is possible to have multiple [[ProviderAPI|providers]], but as they use micro range, there can never be as much providers as clients. In case you seek real '''many to many''' [[proximity]] consider using [[modular library]] design.

Revision as of 19:20, 12 May 2012

Semantic versioning is a natural interpretation of dependencies as described in manifesto at semver.org. It is also a base for designing libraries with few to many proximity between their ClientAPI and ProviderAPI sides.

This proximity is best explained by another semantic versioning proposal defined by OSGi guys. It is using range dependencies to distinguish between ClientAPI (always uses major dependencies range like 1.x to 2.0) and ProviderAPI (which is supposed to always depend on 1.x to 1.(x+1) micro range). This style of versioning opens the vendor library proximity category up to a bit more distant providers. If the OSGi semantic versioning is obeyed, one can use Final interface as a contract between clients of your API and providers of your API. It is expected that in case there is an incompatible change in the Final interface, you bump up the micro version.

Althrough common design practise in OSGi world the drawbacks are obvious. Every change into the API renders all existing providers invalid (as the new version of library is out of their micro dependency range). With every such change all providers need to be rewritten. Should there be two providers written against different version of the API they are unlikely to co-exist together.

Due to these limitations I call this library style a few to many proximity. It is possible to have multiple providers, but as they use micro range, there can never be as much providers as clients. In case you seek real many to many proximity consider using modular library design.

Personal tools
buy