Release guide GN

Our process for making releases in the GN project

Terminology

The terms "release", "version" and "deployment" can be overloaded at times, so let's start with a quick definition.

release

At its most basic level, this is the process of assigning a git tag to a certain commit. In GN, we do a few additional things when releasing, see below for more details

version

A tagged commit which has been released in the above process.

deployment

The act of deploying a certain version to a server. Only ever deploy released commits! See the deployment guide for a how-to.

Release flow

Major or minor releases

In normal circumstances, a release is created on the master branch and contains all commits from the development branch. Therefore, a standard release process looks like this:

• check if all relevant prs have a release-it label (enhancement, bug, internal, documentation or breaking, see below)

• merge development into master and push

• create a release on the master branch (see below). Select major or minor based on your best interpretation of semver. (https://semver.org/lang/nl/)

Bugfix (aka patch or hotfix) releases

Sometimes, an urgent bugfix needs to be released and deployed asap. We cannot simply use the above process, since there might be prs already merged in development which we don't want to deploy along with the bugfix. While this process is mostly for urgent hotfix scenarios, it also applies to bugfix releases which are not necessarily urgent. It is estimated that this situation will be very rare given our current release schedule (every normal release will almost always have bugfixes as well as enhancements)

• consider which minor version this fix is for. This is usually the version currently deployed on production

• If it does not already exist, create a branch with the name of the minor version. e.g.: v2.4

• create a PR with the bugfix against development, as usual

• create a second PR with the bugfix against the release branch. this ensures we can release it in isolation, and keep track of where the versions possibly diverge

• release a patch release on the v2.4 branch

release branches like v2.4 will never get merged back into master or development. They are a record of how a certain release diverged from the main trunk.

Creating a release

At a high level, these are the steps that need to happen for a release:

• make a new commit which appends a list of changes to the changelog.

  • if it's an npm project, also set the package version to the same tag used in the next step

• tag that commit with a git tag using semver with format: v<Major>.<minor>.<patch> e.g.: v2.4.1

• push the commit

• create a github release for that commit with the new changes as its description

• if it's a project hosted on dockerhub, generate a new tagged image (this happens automatically)

In GN, every service, as well as the frontend and the app-repo, get their own release following the above process.

release-it

Of course, this is a lot of work to do manually for every one of the many components of GN. That's why we use release-it to automate it. With release-it, the above process gets reduced to simply running a single command.

how it works

release-it looks for configuration in 2 places: in the package.json, under the release-it key, or in the .release-it.json file. In GN, we only use the .release-it.json file method!

Most repos in GN should already have that configuration file set up. If a repo does not have it, create it instead of releasing manually. Below is a template which we use almost everywhere:

{
  "github": {
    "release": true
  },
  "plugins": {
    "release-it-lerna-changelog": {
      "infile": "CHANGELOG.md",
      "launchEditor": true
    }
  },
  "npm": {
    "publish": false
  }
}

Refer to the configuration docs for more information.

The most important part is the "plugins" section. There we setup the wonderful release-it-lerna-changelog plugin, which integrates release-it with lerna-changelog, which takes care of automatically generating a changelog based on PR titles.

how to use it

read this section through in its entirety first, there are some caveats with the official documentation

Here there are two options. Global installation, or usage through npx. Both are documented in the release-it readme. Make sure to also follow the github setup guide to make sure release-it can push a publish to github. The global installation is more convenient in some cases, but there are some talks about this feature going away from npm, so keep that in mind.

Warning: at the time of writing, there is an error in the documentation for the github setup. Rather than using the GITHUB_TOKEN env var, release-it uses GITHUB_AUTH.

local installation (preferred if available):

Most javascript projects should have an npm script called release, try this first. If it's not available, add it or use the below methods.

global installation:

after setting up release-it as described above, additionally install the lerna-changelog and release-it-lerna-changelog dependencies.

Then simply run release-it in the project root and say yes to all prompts.

npx usage (as from npm v7):

specify the additional dependencies in the command like so npx --package=release-it --package=release-it-lerna-changelog --package=lerna-changelog -c release-it

Unfortunately adding the --package options causes npx to ignore its cache and redownload all deps every time. From a quick search it seems this will be better in npm v7, where npx is integrated into the npm exec command. For now, use the global installation as a faster alternative.