Versioning

Versions need to be simple and consistent, and everyone needs to be on the same page. This guide is intended to pull together the best ideas and keep everything simple.

Versions are two points#

The version will be two points in all cases 1.1, 1.2, 3.5, 21.34

This is compliant with SemVer, its just the patch point doesn’t add any value but adds significant confusion. Its very difficult for developers to decide how much something is broken by a change, its easier to say “Is it breaking or not?”

The version will look like anvil-jenkins-6.1 where anvil-jenkins is the application name 6 is the contract version and 1 is the build number.

Contract numbers increment each time an application introduces a breaking change.

Build automation increments the build number for each successful build

Developers control the contract version

Node rigid SemVer exception#

npm required package.json to have 3 points. So if you have to store a 3 point version the last point should be 0, e.g. package.json versions will end up as 1.1.0, 1.2.0, 2.1.0, 2.2.0 and so on.

Start at 1#

Build numbers start at 1 and increment in ones e.g 1.1, 1.2, 1.3… 1.12, 1.13

Contracts start at 1 and increment 1.15, 2.12, 3.5… 7.45, 8.2

Zero has no meaning, all that happens is that things always sit at 0 because they are never ready. We argue that if you have committed it, you have exposed it, so its already past 0 just own it.

Library versions#

Library versions are meaningless and super meaningful at the same time. The key for library is compatibility. Contract versions are used to roll out breaking changes without affecting downstream libraries. The downstream can choose when to upgrade.

Application Versions#

Applications versions are meaningless and super meaningful at the same time. They facilitate our ability to communication about where our development progress is at.

Expose your version#

Each application needs to export /version/ at runtime which returns the current tag the application was built from. This means the current version should be stored as part of the release process and can be examined at runtime.

This is used to validate the application is running the correct version when doing continuous delivery.

The version should be returned as plain/text and look like this

  anvil-jenkins-6.1

Product versions#

Groups of applications that are released together in units are called Products, they have their own version that follows the same rules.

Products use ranges to collate applications e.g.

The collation happens at build time of the Product manifest that is released as a zip into the Binary Repository Manager

Versions for the various build tools#

Here is summary of where to find the versions for applications and libraries using tools maven, npm and Gradle

Maven projects#

The pom.xml version is what is used to manage it, the versions look like this

<groupId>io.practiv.stable.chalk</groupId>
<artifactId>anvil-jenkins</artifactId>
<version>1.999-SNAPSHOT</version>
<packaging>jar</packaging>

The version 1.999-SNAPSHOT defines a contract version of 1, Jenkins will replace the 999 with the next tag version at build time.

The 1.999 is used such that when you open projects in Eclipse or install from the command line that the manually install version overrides all release versions.

Gradle Projects#

The gradle.properties file contains the versions

name=anvil-jenkins
group=io.practiv.stable.chalk
version=0.999

The version 0.999 defines the contract version of 0 and Jenkins will replace the 999 at build time