= Aries versioning policy

The Aries  project aims to implement OSGi semantic versioning as described http://www.osgi.org/wiki/uploads/Links/SemanticVersioning.pdf[here].

The implementation of semantic versioning has a number of practical implications for managing a project.
These are outlined in this section.

== Package versions

=== Exported packages Versions are usually specified in packageinfo files with the source code.
The default-parent pom is  configures (in the build resources section) to expect packageinfo files.
If your pom has a build resources section it replaces what is inherited from the default-parent, so you may need to reproduce  the section which specifies where packageinfo can be found.

Developers *must* increment the versions in packageinfo files in strict accordance with OSGi semantic versioning when they make changes to a package.
The version should relate to the *most recent release of the package* and not to the version found in trunk.
For example:

==== Scenario 1, making changes to a package with released version a.b.c

* Developer A fixes a bug in the package and increments it's version to a.b.c+1
* Developer B fixes another bug in the package but leaves the version at a.b.c+1

==== Scenario 2, making changes to a package with released version a.b.c

* Developer A adds a method to an interface in the package and increments it's version to a.b+1.0
* Developer B fixes a bug in the package, leaves its version at a.b+1.0

==== Scenario 3, making changes to a package with released version a.b.c

* Developer A fixes a bug in the package, and increments its version to a.b.c+1
* Developer B deletes a method from an interface and increases the package version to a+1.0.0.
Note the final '0' here, developer B's change is more significant so there is no need to reflect Developer A's change with a micro version of '1'.
Indeed, a version of a+1.0.1 would imply a bug fix to version a+1.0.0.

=== Importing packages

The bnd default version range policy for imports is the consumer policy (==, +).
Implementers of interfaces will need to  override this.
For example as an implementer of an interface the version range  would be the provider policy (==,=+).
The policy can be set by using the Maven property +++<aries.osgi.version.policy>+++, see the default-parent pom for an example.+++</aries.osgi.version.policy>+++

== Bundle versions

*Note: Bundle versions are changed at release time and only by the release manager.
Bundle versions are not updated during development.*

OSGi semantic versioning applies to bundles as well as packages.
When releasing a new version of a bundle the change in the bundle version should give some indication of nature of the changes to the bundle.
In Aries the bundle version is the same as version of the Maven artifact version.
During development, in trunk, the Maven artifact version will be:

* x.y.(z+1)-SNAPSHOT

Where x.y.z is the most recent release of the bundle

During the release process the Maven release plugin asks for a the subsequent version to use in the module's pom after the release has taken place.
The default is to increment the last digit and add -SNAPSHOT.

For example, if proxy is released at version 1.0.0, the development version of proxy in trunk will become 1.0.1-SNAPSHOT.

In addition, after a release, modules dependencies should refer to the lowest released version providing enough exported functionality the bundle requires.
This ensures the import version is automatically set correctly to allow for loose coupling supported by OSGi.

For example, bundles which depend on proxy (e.g.
blueprint) will be set to depend on the released version of proxy.
Immediately after  a release of proxy at say 1.0.0 and a release of blueprint at 1.2.0, the development version of blueprint in trunk will be 1.2.1-SNAPSHOT but the version of proxy that it depends on will be 1.0.0.

=== Assigning a bundle version number at release time

At release time the release version of the bundle must be assigned by the release manager after reviewing the changes to the bundle's package versions since the last release.
This is not a particularly time consuming task as long as  packageinfo files are used for versioning packages.

So, for example, if proxy has a version of 1.0.1-SNAPSHOT in trunk but one of the API's that is exported by proxy  has changed its package version from 1.3.4 to 2.0.0 in trunk, the bundle version would be incremented to 2.0.0 on release to indicate an incompatible change in (at least) one of its packages.

Bundles that don't export any packages will still change version when bugs are fixed.
In this case the new release version will be x.y.(z+1) if the last release was x.y.z.