Andrew Rea

Andrew Rea


Stuff about programming, security and technical architecture

Andrew Rea
Author

Share


Twitter


Component & API Versioning

Semantic Versioning The format for the version is: <Major>.<Minor>.<Patch>[.<BuildRevision>][-<Informational Version>] Component V…

Andrew ReaAndrew Rea

Semantic Versioning

The format for the version is:

<Major>.<Minor>.<Patch>[.<BuildRevision>][-<Informational Version>]

Component Versioning

All components are versioned independently of each other. The version of any component is stored inside a VERSION file which is stored at the root of the source code repository for the component. A component is any project, application, library within a system which can be changed.

When, Why and What to increment

When

Major, Minor or Patch versions (only one) will be incremented (by one) at the time a release candidate it created.

Build Revision versions will be incremented at the discretion of the developer team so that the correct versions can be added at development time.

Why

A useful way to think about semantic versioning is .. which means:

  • Increment the Major if the release contains one or more breaking changes.
  • Increment the Minor if the release contains one or more features.
  • Increment the Patch if the release contains one or more bug fixes.

https://medium.com/javascript-scene/software-versions-are-broken-3d2dc0da0783

What

When a release contains one ore more bug fixes, features or breaking changes the following rules guide which part of the version to increment.

  • Major trumps Minor.
  • Minor trumps Patch.
  • Only one version part can be incremented per release.
  • A version part can only be incremented by '1' per release.

Examples:

  • Component 1 ( Release 2 ) started at v0.1.0, it contains 3 bug fixes, it is released at v0.1.1
  • Component 1 ( Release 3 ) started at v0.1.1, it contains 2 features and 1 bug fix, it is released at v0.2.0
  • Component 1 ( Release 4 ) started at v0.2.0, it contains 1 breaking change, 3 features and 3 bug fixes, it is released at v1.0.0

Informational Versions

The current project I am on follows a feature branch strategy using a permanent develop and master branch and temporary branches for features, releases and hot-fixes.

Any push to one of a component's feature branches will result in the version being suffixed with the '-' and it will replace any other versions of the same name in the artefact repository. This allows the team to get the latest build for a particular feature that is not yet in the develop branch.

Any push to a component's develop branch will result in the version being suffixed with '-develop' and it will replace any other versions of the same name in the artefact repository. This allows the team to get the latest development build that is more stable that a feature build.

Any push to a component's release branch will result in the version being suffixed with the -rc<n> where n is an incremented value based on the number of pushes to the release branch, each push will increment the rc number (release candidate). Once a release branch has been created, only hot fixes to that release are permitted.

System Versioning

The overall system version is calculated based on the versions of its components. As with the rules for versioning, the system version will take the most significant version of the components as the indicator as to which version part to increment e.g. A system is currently on v1.0.0, it has five components, two have been patched, two have had new features added and one has had a breaking change applied therefore the system will now be at v2.0.0.

Release Notes

The release notes contains every pull request into the develop branch since the last release. Each of the feature branches contain the ticket id which allows for the release notes generation to include the title from Jira (or whatever tool you use) using its API. If there are no changes to a component in a release, this is clearly stated underneath the component title.

House keeping

Any release candidate versions should be deleted following a successful release as they are superceded.

API Versioning

https://tyk.io/blog/when-and-how-do-you-version-your-api/

  • The APIs will only be versioned using the Major.Minor versioning components.
  • Minor versions will be incremented due to any changes which DO NOT break backwards compatibility.
  • Major versions will be incremented due to any changes which DO break backwards compatibility.
  • Only the Major version needs to be specified by the API client. This only needs to be specified once the first backwards breaking change has been made to the API.
  • The API version needs to be supplied via the Accept HTTP Header e.g. Accept: application/api.dft-bluebadge.org.uk.v3+json

Examples of Backwards Breaking Changes

  • Removing a property from a contract.
  • Changing the name of a property in a contract.
  • Changing the HTTP Verb required.
  • Changing the Context Validation.
  • Changing the URL.
Andrew Rea
Author

Andrew Rea

Comments