Versioning

Versions are important.

Accurate versioning is important for several reasons:

  • ensure compatibility and traceability of new features in the application and API;
  • documentation of functionality with reference to the specific version in which these capabilities appeared;
  • designation of the current status of software product readiness (pre-release, alpha, beta);
  • planning new functionality (road map).

Version Number

Traditionally, a version consists of several numbers separated by a dot.

Most often, a three-part template is used for versions numbering: X.Y.Z (major.minor.patch).

Numbering rules:

  • major changed in case of significant changes breaking backward compatibility;
  • minor changes in case of adding functionality (new methods to the API);
  • patch changes when fixes and minor improvements are made to existing functionality.

Semantic Versioning

It is most convenient to follow the rules of semantic versioning when numbering versions.

Semantic versioning (aka SemVer) is a widely-adopted version scheme that uses a three-part version number (Major.Minor.Patch), an optional pre-release tag, and an optional build meta tag.

Semantic versioning allows the use of zero as a major version number, which is an exception to the general system of rules and introduces a lot of inconsistency. It is strongly recommended to avoid this and start numbering from version 1.0.0, or use 0.Y.Z only for internal development and publish to users already with version 1.0.0-alpha.

For convenience, you can use the fourth component of the version number (major.minor.patch.build) for continuous numbering with each new build of the program.

Versioning Scheme

Development
 1.0.0-1
 1.0.0-2
 1.0.0-3
 ...

Alpha versions
 1.0.0-alpha.1
...

Beta versions
 1.0.0-beta.1
...

Pre-releases
 1.0.0-rc.1
...

Release
 1.0.0

Versions in API

Adding a version number to the API will allow you to ensure a seamless transition to a new version of the API when adding new features in the application. For example, adding a version number to the REST API URL will make it possible to support two versions at the same time, if required.