Semantic versioning
From APIDesign
(New page: A natural interpretation of dependencies as described in manifesto at http://semver.org/) |
|||
| (4 intermediate revisions not shown.) | |||
| 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. | |
| + | |||
| + | 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 [[ProviderAPI|providers]] need to be rewritten. Should there be two providers written against different version of the [[library]] they are unlikely to co-exist together (because of versioning, otherwise they very likely could as commonly the case in [[modular library|modular libraries]]). | ||
| + | |||
| + | 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. | ||
Current revision
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 library they are unlikely to co-exist together (because of versioning, otherwise they very likely could as commonly the case in modular libraries).
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.
Follow
