knowledge-kitchen

Release Management - A Disciplined Approach to Versioning Software Releases

An organized approach to versioning software releases.

1. Overview
2. Semantic Versioning
3. Calendar Versioning
4. Git Tags
5. GitHub Releases
6. Conclusions

Overview

Concept

Release management is the streamlined approach to issuing software releases.

Contents

What is in a release? The following are some common contents:

• the working software

• configuration files

• data files, including any data migration scripts

• an installation program

• documentation

• marketing and promotion materials

Release Timing

The date on which a release is published is often dependent upon a number of factors:

• level of effort to complete the release

• the release schedules of technical dependencies

• the release schedules of the competition

• marketing parternships and promotions

• business reasons why one particular date might be better than another

Semantic Versioning

Concept

Software versions using the Semantic Versioning system take the form of:

X.Y.Z

e.g. Ubuntu 20.04.3, MacOS 13.4.1, Python 3.9.7, Node.js 16.9.1

Where…

• X is the major version number
• Y is the minor version number
• Z is the patch number

Prefixes

There is some debate as to whether a version number should be prefixed with a v as in v1.0.2 instead of simply 1.0.2.

• For our purposes, it doesn’t matter. See more discussion about this here.

Rules

Semantic Versioning involves 12 rules. The first 8 are the most important and are included here.

Rule 1: Public API

Software using Semantic Versioning must declare a public API. This API could be declared in the code itself or exist strictly in documentation. However it is done, it should be precise and comprehensive.

Rule 2: Version Number Format

A normal version number must take the form X.Y.Z where X, Y, and Z are non-negative integers, and must not contain leading zeroes. X is the major version, Y is the minor version, and Z is the patch version. Each element must increase numerically. For instance: 1.9.0 -> 1.10.0 -> 1.11.0.

Rule 3: Immutability of Versions

Once a versioned package has been released, the contents of that version must not be modified. Any modifications must be released as a new version.

Rule 4: In-Develepment API Version

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

Rule 5: Initial Public API Version

Version 1.0.0 defines the public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes.

Rule 6: Patch Versions

Patch version Z (x.y.Z

x > 0) must be incremented if only backwards compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior.

Rule 7: Minor Versions

Minor version Y (x.Y.z

x > 0) must be incremented if new, backwards compatible functionality is introduced to the public API. It must be incremented if any public API functionality is marked as deprecated. It MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes. Patch version must be reset to 0 when minor version is incremented.

Rule 8: Major Versions

Major version X (X.y.z

X > 0) must be incremented if any backwards incompatible changes are introduced to the public API. It MAY include minor and patch level changes. Patch and minor version must be reset to 0 when major version is incremented.

Criticisms

While Semantic Versioning is arguably the most popular formalized approach to the problem versioning, it does have its critics.

• For example: Rich Hickey’s Semantic Versioning is a Lie and Hynek Schlawack’s Semantic Versioning Will Not Save You

• Criticism tends to focus on the fact that, in practice, patches and minor version updates often result in broken applications, despite the best of intentions.

• In that context, semantic versioning’s clear rules seem like wishful thinking that belies a more complex reality.

Calendar Versioning

Overview

Calendar versioning is a simple approach to versioning software releases. It uses the date of the release as the version number.

• The date is the only version number.

• There is no concept of a major, minor, or patch version.

• No concept of a “public API”.

• The spec provides flexibility in how the date is formatted.

Essentially a fancy version of the time-tested technique of naming your files with the date in the filename.

When to use

Calendar Versioning is a good choice when:

• your project features a large or constantly-changing scope (i.e. new versions are difficult to plan ahead)

• your project is time-sensitive (i.e. time is a major factor driving new releases)

• other external changes drive new project releases (i.e. new releases are not driven by planned changes in functionality)

Example

Your old my-homework-01-10-2023.txt file now becomes a my-homework repository tagged with version 2023.01.10

Date format

While Calendar Versioning supports multiple date formats, when in doubt, use YYYY.MM.DD, where YYYY is the four-digit year, MM is the zero-padded month, and DD is the zero-padded day.

• This simplifies sorting by date. The standard date format in the US, MM.DD.YYYY, is an embarrassment for sorting.

e.g. do this: 2023.01.10, not this: 01.10.2023

Git Tags

Concept

Git’s tagging features can be used to mark the repository at a moment in time as a particular release.

Create Tag

Create a tag on the currently checked-out branch, labeling it as release version 1.0.0:

git tag v1.0.0

… or, if using a calendar versioning tag:

git tag 2023.01.10

Create Tag with a Message

Leave an optional message to go along with a tag.

git tag -a v1.0.0 -m "initial version of the coffee grind future fineness predictive algorithm"

Push Tag

Push the release to an upstream remote repository, such as GitHub:

git push origin v1.0.0

Switch to Tag

Checkout code from the main branch as it was at release version 1.0.0:

git checkout -b main v1.0.0

GitHub Releases

Concept

GitHub repositories have a ‘Releases’ page, linked from sub-navigation links in the ‘Code’ tab.

GitHub’s Releases functionality can complement the Git tag for a release and make it more intuitive to find a project’s official releases.

Conclusions

Thank you. Bye.