Versioning in software development

Posted on by user

The versioning scheme follows the structure: <Major-Release>.<Minor-Release>.<Maintenance-Build-Level>.

  • Corrections of bugs are to be implemented without altering the API; such changes are invisible to the user of the API and result in an increase of the Maintenance-Build-Level.
  • The introduction of new features should not interfere with existing API functionality. Users have the discretion to adopt these features. This type of update leads to an increment in the Minor-Release number.
  • Updates termed as Major-Releases might break backward compatibility. Therefore, it is required that the previous version remains accessible for a specified deprecation period to facilitate a smooth transition.

Versioning in software development is a critical component for managing changes and ensuring that users and developers can track and understand the evolution of a product. Here’s an explanation of the typical three-digit versioning scheme:

1. Major Release (<Major-Release>):

  • The first digit in the versioning scheme is the Major Release number. It indicates significant changes to the software, which may include backward-incompatible changes. This means that when the Major Release number is incremented (e.g., from 1.x.x to 2.x.x), the changes are substantial enough that they may require users to modify their own code or configurations to work with the new version.
  • A Major Release often introduces new features, major enhancements, and potentially breaking changes that could affect the way the API functions. Because of these potential breaking changes, best practices dictate that the previous major version should be maintained for a period of time to allow users to transition. This is known as the deprecation period.

2. Minor Release (<Minor-Release>):

  • The second digit is the Minor Release number. It is incremented when new features or functionality are added, but in a way that does not break backward compatibility. This means that all the functions that worked before the update will continue to work after the update.
  • For example, going from version 1.2.x to 1.3.x would imply that new features have been added, but everything that worked on version 1.2.x should still work on 1.3.x. The API user can choose to implement and use the new features or continue operating as before.

3. Maintenance Build Level (<Maintenance-Build-Level>):

  • The third digit represents the Maintenance Build or Patch Level. It is increased when bug fixes, security patches, or other minor changes that do not affect the API’s external behavior are released.
  • These updates are intended to be completely transparent to the user and should not alter the functionality from the user’s perspective. If you update from version 1.2.1 to 1.2.2, you should expect no changes in functionality, just improvements or fixes to existing features.

Examples of Version Changes:

  • 1.2.3 to 1.2.4: A bug was fixed, no new features, and existing API calls remain unchanged.
  • 1.2.4 to 1.3.0: New features added, but all existing API calls remain functional and unchanged.
  • 1.3.0 to 2.0.0: Potentially breaking changes, the software has undergone significant updates that may affect existing API calls or how the system is used.

When designing and managing an API, it’s essential to communicate clearly about version changes and the implications of each update. This means providing detailed release notes, updating documentation, and, if possible, providing migration guides for major releases. This level of communication helps prevent disruption and ensures that users can update to newer versions with a clear understanding of what to expect.