Release process

Release process

This page documents the process around making new releases for SciGateway & it's plugins.

Preparing a release

First, make sure you have the latest develop branch, and then make a new release branch from develop - using the naming schema of release/vX.Y.Z - with X, Y and Z matching the new major, minor and patch numbers of your release.

git checkout develop
git pull
git checkout -b release/vX.Y.Z

On this branch, we need to update the version numbers and update the changelog. Both of these things can be done manually, but we can also use tools to help us.

Updating version numbers

To update the version numbers, you can run the following command to bump the version number in package.json

yarn version X.Y.Z

If you're bumping it in DataGateway, then you need ensure you run this command in each of the packages.

Updating changelog (old)

We use a tool called github_changelog_generator to generate the changelog. This is a Ruby tool, and the easiest way I found to set this up was to use RVM and if you're on windows the easiest way to do this is via WSL. Either way, I hope to automate the changelog generation soon anyway, but this is still useful. So install github_changelog_generator according to it's docs. Then you just need to run the following command:

github_changelog_generator -u "ral-facilities" -p "scigateway" --token="YOUR_TOKEN" --base CHANGELOG-BASE.md --exclude-tags snapshot,snapshot-develop --future-release vX.Y.Z --since-tag v1.0.0

Obviously, replace scigateway with whichever repo you're releasing, as well as replacing YOUR_TOKEN with a Github personal access token (github_changelog_generator has instructions on how to do this)

You may need to go through and check that all the relevant PRs have been tagged with the appropriate labels (enhancement, bug, security etc) to ensure they're put in the correct sections in the generated changelog.

Update changelog (new)

Go to the GitHub releases page, and go to the snapshot-develop release. This tag should match the code you're about to release, so you can use GitHub's "Generate Release Notes" feature to create the changelog. Press this button, then copy the generated log into the CHANGELOG.

Ensure however to replace any reference to the snapshot-develop tag with actual tag (vX.Y.Z). Also, give a nice title by copying the header from the previous release

Commit your changes & create a PR

Now that you have changed the version numbers and updated the changelog, you just need to commit and push your changes as normal. Then, create a PR from your release branch to main - this is important! You want to merge the changes to main and not develop, as that updates the main branch with all the changes from develop since the last release.

Releasing

Now that you've prepared your release branch and created a PR from it to main, get the PR reviewed as normal. Once you're happy, merge the PR into main.

Now, you have to tag that commit as the release. Run the following commands:

git checkout main
git pull
git tag vX.Y.Z
git push origin --tags

This should tag the main branch with the latest commit (which is the merge from your release branch into main) and push that tag back to Github.

Github Actions should now automatically create your release and attach the built versions to it as well as creating release notes.

Finally, develop is missing the commits from main so we need to merge them back in. This step is important for future releases as the changelog generator works off of tags, and so the commit that is tagged needs to be on develop. develop also just needs the version number and changelog changes as well!

git checkout develop
git pull
git merge main
git push

You may need to disable branch protection rules to be able to do the above. You can alternatively do this via a PR which obeys the branch protection rules.

On DataGateway - remember to run yarn install before finishing the merge - as the lockfile will need to change with the updated datagateway-common version