modules/ROOT/pages/development/versionpolicy.mdtext - aries-antora-site - Git at Google

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