# Aries versioning policy

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

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.

## 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.