Skip to content

Release Process

Jump to bottom
Joel Davies edited this page Jun 26, 2025 · 15 revisions

Note

This page should match https://github.com/ral-facilities/ldap-jwt-auth/wiki/Release-Process. But with any changes specific to the front end. Right now these changes are

  • pyproject.toml -> package.json.
  • Additional warnings on ensuring the correct branches on End-to-End (with api) are used.

Branches

  • develop is the default branch that should be used for development and is the one that gets dependabot updates
  • main should be the latest release branch
  • v1.x, v2.x are release branches that should only be created from main when older versions must be maintained e.g. if a facility cannot upgrade immediately due to migrations.

For general releases

When it is time to release the following steps should be followed

  1. Create a branch for the specific release e.g. vX.Y.Z from develop
  2. Update the version within the package.json following https://semver.org/
  3. Create a PR merging the new branch from 1. into the appropriate release branch (e.g. main, v1.x etc), resolving any merge conflicts and requesting a review as required

Warning

The End-to-End (with api) tests on the CI should be checked and modified if necessary to ensure the appropriate ims-api branch is being used.

  1. Merge the PR and delete the branch from step 1
  2. Go to the GitHub Releases section and create a new release
    1. Creating a new tag of the version in the form vX.Y.Z
    2. Select the release branch as the target and click Generate release notes (Then modify as appropriate)
    3. Ensure Set as the latest release is checked as appropriate
    4. Click Publish release

This will trigger the release-build action that will generate and push a new Docker image to Harbor with the tags X.Y and X.Y.Z.

  1. Create a PR to merge the release branch back into develop to ensure any new commits are added

Caution

DO NOT delete the release branch after merging the PR in step 6.

For a bug fix on a release

If there is a bug that needs fixing on a specific release branch. The changes are most easily made on that release branch. After the required fixes are merged, the changes can be merged up into any newer release branches and then into develop. To release follow the same steps as for general releases but use the release branch instead of develop for step 1.

For a Docker image patch

If only updating a Docker base image (e.g. for a security update), a patch version is not required. In this case you should

  1. Merge the update into the appropriate release branch
  2. Pull the release branch locally
  3. Ensure any local tags have been removed e.g. git fetch --prune --prune-tags
  4. Tag the release branch with the same latest tag for that release branch e.g. git tag vX.Y.Z --force (The force is needed as it should already exist)
  5. Then push the tags to origin using git push origin <release branch> --tags --force

This will trigger the release-build action that will generate and push a new Docker image to Harbor with the tags X.Y and X.Y.Z. The release notes do not need updating in this case.

Warning

Do NOT attempt to patch a non latest patch version this way, as the X.Y tag should point to the latest version of the minor release.

  1. Create a PR to merge the release branch back into develop

Caution

DO NOT delete the release branch after merging the PR in step 6.

Warning

The End-to-End (with api) tests on the CI should be checked and modified if necessary to ensure the appropriate ims-api branch is being used.

Notes

Dependabot Docker image and GitHub Action PR updates

You should merge Dependabot Docker image and GitHub Action PRs into the release branch rather than develop. This way you will not need to cherry pick any of the commits if these updates went into develop first. To do this, follow the steps below:

  1. Change the base branch from develop to the release branch from the PR on GitHub.
  2. Checkout and pull the latest change for the PR branch locally.
  3. Rebase the PR branch on top of the release branch (Please note that if you try to do the rebase with dependabot directly from GitHub then it will change the base branch back to develop). 
    git fetch origin
git rebase <release branch>
  4. Push the changes to remote. 
    git push --force-with-lease

Cherry picking Docker image or package updates onto a release branch

If you wish to update a Docker image or package update on a release branch that has already been merged on develop without merging all other changes on the current develop branch, use the following steps:

  1. Checkout a new branch to be merged into the release branch e.g. update-dependencies
  2. Find the commit SHA of the update commit(s) you wish to put onto the release branch (can be found through git log or via GitHub) - Merge commits should be ignored.
  3. While on the new branch use git cherry-pick commitSha1 commitSha2 ... to copy the commits onto the new branch
  4. Create a PR merging the new branch into the release branch

Clone this wiki locally