[ADP-24] Versioning Mechanism

Introduction

In the world of software development, Semantic Versioning (SemVer) is a widely adopted versioning scheme that provides clear and concise rules for assigning and incrementing version numbers. This document outlines the mandatory requirements for following Semantic Versioning in our API development and release process.

We will face versioning at different topics in API design such API versioning, content type versioning and event versioing.

What is Semantic Versioning?

Semantic Versioning, also known as SemVer, is a versioning system designed to convey meaning about the underlying changes in a release. A version number is in the format of MAJOR.MINOR.PATCH, where:

• MAJOR version changes indicate incompatible API changes.
• MINOR version changes add functionality in a backward-compatible manner.
• PATCH version changes are for backward-compatible bug fixes.

Version Format

The version format follows the pattern: MAJOR.MINOR.PATCH (e.g., 1.0.0).

TIP

💡 In API versioning, another approach to denote versions is by using the release date. This method still adheres to Semantic Versioning principles; only major or minor changes would affect the release date. Example: If the current version is 1.0.0 released on 2024-01-01, and a backward-compatible feature is added, the new version could be 1.1.0 with a release date of 2024-02-15. For a breaking change, the version would be 2.0.0 with the corresponding release date.

Guidance

• MUST Follow SemVer: Adherence to Semantic Versioning (SemVer) is mandatory for all versioning practices.
• MAY Ignore PATCH Number in Some Cases When Being Displayed: In certain scenarios, the PATCH number can be omitted from the displayed version, provided that the context makes it clear that only minor or major changes are being referenced.
• MAY Ignore PATCH and MINOR Numbers in Some Cases When Being Displayed: In specific situations, both the PATCH and MINOR numbers can be omitted from the displayed version, especially when communicating major version changes or when the additional detail is unnecessary for the audience.

Implementation Detail

MAJOR Version Increment

• The MAJOR version MUST be incremented when you make incompatible API changes.
• Incompatible changes include removing, renaming, or altering the behavior of existing endpoints in a way that could break existing clients.
• Example: If the current version is 2.4.3 and you introduce a breaking change, the new version will be 3.0.0.

MINOR Version Increment

• The MINOR version MUST be incremented when you add functionality in a backward-compatible manner.
• This includes adding new endpoints, new parameters to existing endpoints (as long as they are optional), and any other additions that do not break existing functionality.
• Example: If the current version is 2.4.3 and you add a new endpoint, the new version will be 2.5.0.

PATCH Version Increment

• The PATCH version MUST be incremented when you make backward-compatible bug fixes.
• Bug fixes include resolving issues that do not affect the API's interface or add new functionality but improve the stability and performance of the current version.
• Example: If the current version is 2.4.3 and you fix a bug, the new version will be 2.4.4.
• Based on the strategy, the PATCH version number might not being displayed.

Reference

• Semantic Versioning Specification (SemVer)