OEP-47: Semantic Versioning

OEP-47: Semantic Versioning#

OEP

OEP-0047

Title

Semantic Versioning

Last Modified

2020-05-28

Authors

Robert Raposa <rraposa@edx.org>

Arbiter

Régis Behmo <regis@behmo.com>

Status

Accepted

Type

Best Practice

Created

2020-03-19

Review Period

2020-05-11 - 2020-05-25

Summary#

For any Open edX repository that publishes versioned packages, this OEP recommends following the PEP 440 compatible sections of Semantic Versioning v2.

The most relevant part from the summary of the Semantic Versioning v2 specification:

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes,

  • MINOR version when you add functionality in a backwards compatible manner, and

  • PATCH version when you make backwards compatible bug fixes.

From PEP 440 (quote updated to match 2.0.0 of the spec):

The “Major.Minor.Patch” (described in this PEP as “major.minor.micro”) aspects of semantic versioning (clauses 1-8 in the 2.0.0 specification) are fully compatible with the version scheme defined in this PEP, and abiding by these aspects is encouraged.

Some additional tips are called out in:

Note

This OEP does not apply to repositories without versions. For example, services like edx-platform, ecommerce, etc. do not have versions.

Context#

Many or all of the Open edX installable libraries already use versions similar to the Semantic Versioning v2 specification. This OEP simply codifies this best practice, and provides additional guidance.

Backward Incompatible Changes#

Special attention should be given to incompatible changes, because:

  • Communicating incompatibilities alerts humans to possible problems when attempting to upgrade your package.

  • A MAJOR version is what is used to communicate any “Backward Incompatible Changes” (also known as “Breaking Changes”).

See related FAQ questions from Semantic Versioning v2:

Tooling and Automation#

  • A checklist item in a pull-request template can remind people of any manual steps.

  • Some frontend libraries have been using an npm package called semantic-release. The semantic-release package automates incrementing the version appropriately for each PR merge, based on a well formatted commit comment.

    • One important formatting detail is to include “BREAKING CHANGE” at the beginning of a line in the commit description to get a new major version.

  • Other tools can be added here over time.

Versions for Forks#

We sometimes maintain forks of open source libraries. In these cases, the version should follow the recommendation of the Python community, which is to add a +edx.1 suffix to the end of the public version number.

References#