Canary Version Management

In open source projects, a more standardized version management scheme is needed. Here we will discuss the practical application of canary versions.

Canary Versions of Next.js

While looking at the next.js repository, I noticed that it doesn't have a main/master branch, however, it has a canary branch instead. There are many canary versions between tags. This caught my interest.


By observation, PRs in Next.js will use Squash and Merge and delete the merged branch. The new version will start from xxx-canary.0, and after some testing fixes, it will be released as an official version number. I am unsure of the change period and what the criteria are for next.js to publish an official version.

In the versions I used to manage, adding new features would result in an updated patch version. However, when issues were discovered and fixed, another patch version would need to be released immediately. This version was intended only to fix issues in the previous version. Unfortunately, this casual practice has resulted in some unusable versions.


The canary stage can significantly improve the problem. It also serves as a reminder not to casually release a new version number. Sufficient time and testing are required before doing so.

How to publish a canary version:

npm publish --tag canary

Origin of the Canary

The practice of using canaries as an early detection system for toxic gases originated from coal miners.

In 1911, British miners introduced canaries into mines. These birds are highly sensitive to carbon monoxide, and even a small amount of leakage can cause them to become restless, chirp, or die. When the canaries display these symptoms, miners know that there is dangerous gas in the mine and they must evacuate.

Over time, the term "canary" has come to represent the early detection and feedback of software.


In the new version of my react18-json-view, I have adopted the new approach. A version now starts as a canary version and, after a certain number of canary versions, it is replaced by an official version.

Versioning Specification

Semantic Versioning 2.0.0

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

  1. MAJOR version when you make incompatible API changes
  2. MINOR version when you add functionality in a backward compatible manner
  3. PATCH version when you make backward compatible bug fixes

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

In my opinion, a minor version should be an accumulation of certain features from previous patches. Usually, the patch version number is still added even if some features are included. For example, consider the minor version change of next.js: