Changes to our release branches

Julian Lam 7/26/2022, 2:18:20 PM

What is a release branch?

Whenever we make a NodeBB release, whether it be a patch release, minor release, or a major release, we also push the code to specific release branches, for those who wish to subscribe to a specific set of releases.

For example, an administrator who currently runs v1.18.0 of NodeBB might not want to pull the latest code and upgrade all the way to v2.2.5 (as of this writing). They may want to upgrade to the latest version on the v1.18.x release branch, which is v1.18.6. By tracking the release branch, they are safe from accidentally upgrading to a potentially breaking version of NodeBB.

Why the change?

Up until recently, we released new versions when we felt it was safe to do so. A patch version could contain new functionality in addition to bug fixes, and minor versions contained breaking changes. A major version bump denoted a radical change (e.g. the switch to webpack.)

However, lumping in enhancements and bug fixes meant that occasionally, regressions and unexpected behaviour could occur during upgrades.

Since the dawn of version 2.0, we wanted to accelerate our release schedule, and remove any roadblocks to a patch release. More information is provided in the semver blog post, but in short:

  • Patch versions contain bug fixes only
  • Minor versions contain bug fixes and enhancements
  • Major versions contain breaking changes

What's the change?

Instead of creating a new release branch on every minor release (e.g. v1.19.x, v2.0.x, v2.1.x...), we will create one for every major release:

  • A v1.x branch will be created, and security fixes will be backported there
  • A new v2.x branch will be created, and new releases for v2 will be pushed there
  • As we continue to work on NodeBB, we will create additional release branches (e.g. v3.x, v4.x...) as major releases are made
  • master will remain the main git branch, but will see less activity, as only bug fixes will be pushed there.
  • The develop branch will contain new functionality.
  • Every time a minor release is made, develop will be merged into master.

What do I have to do?

If your NodeBB installation currently tracking a release branch, you can run the following commands:

  • For v2.x: git fetch && git checkout v2.x
  • For v1.x: git fetch && git checkout v1.x

Alternatively, if you wish to pin your installation to a specific version, your best bet is to track the master branch and git reset as necessary:

  • git fetch
  • git checkout master
  • git reset --hard v2.2.5

Notes