1. Semantic Versionning
Sources
version ::= <major> [ ‘.’ <minor> [ ‘.’ <micro> [ ‘.’ <qualifier> ]]]
- major — Packages with versions that have different major parts are not compatible both for providers as well as consumers. For example, 1.2 and 2.3 are completely incompatible.
- minor — API consumers are compatible with exporters that have the same major number and an equal or higher minor version. API providers are compatible with exporters that have the same major and minor version number. For example, 1.2 is backward compatible with 1.1 for consumers but for providers it is incompatible. Consumers should therefore import [1.2,2) and providers should import [1.2,1.3).
- micro — A difference in the micro part does not signal any backward compatibility issues. The micro number is used to fix bugs that do not affect either consumers or providers of the API.
- qualifier — The qualifier is usually used to indicate a build identity, for example a time stamp. Different qualifiers do not signal any backward compatibility issues.
Square brackets ( ‘[’ and ‘]’) indicate inclusive and parentheses (‘(’ and ‘)’) indicate exclusive. That is, [1.2,2.0) indicates the version range from version 1.2, including version 1.2, up to but not including version 2.0.
a) Import-Packge: com.myorg.package1 b) Import-Packge: com.myorg.package1;version=1.0.0 c) Import-Packge: com.myorg.package1;version=[1.0.0, 1.0.1) d) Import-Packge: com.myorg.package1;version=[1.0.0, 2.0.0)
Using (a) any version might match and it could walk you right into the classic pitfall of resolving against higher major versions. Doing so has the potential to break you at runtime because of interface changes. Using (b) any version from 1.0.0 upwards might resolve and you incur the same problems as (a). Most developers end up with such a configuration because it’s usually the default tooling generated configuration. Using (c) imposes a very restrictive match, the curved bracket implies higher versions are excluded. Using this approach requires updates and redeployment of the application for every bug-fix in your chain of dependencies. Using (d) is a happy medium. Bug fixes and API additions are tolerated without change. If there is an API breakage the OSGi bundle fails to resolve and protects you from a potential runtime failure.