Creating Hotfix Releases - digitalgroundgame/pragmatic-papers GitHub Wiki

← Table of Contents

Overview

Our branch protection rules require a Pull Request (PR) to be reviewed and approved before merging.

This means we need to create a new branch from main, make our changes, create a PR, get it reviewed and approved, then merge.

This process is repeated a second time in order to back-merge those changes from main to dev via a second branch and PR.

The flow is:

hotfix/my-hotfix    →  PR → main       (branch off main)
chore/back-merge    →  PR → dev        (branch off dev, merges origin/main)

Why is this necessary?

Hotfixes on main allow us to make time-sensitive patches to production. This way we can address critical problems without having to wait for a full dev branch release.

Back-merging ensures dev has all production changes, keeping the branches' content in sync.

Step by Step

  1. Create a new branch from main

Hotfix branches must be prefixed as hotfix/*

git checkout main
git pull origin main
git checkout -b hotfix/my-hotfix-branch
  1. Make your changes

Since we squash-merge in step 4, commit freely here — it all becomes a single commit on main.

Remember to bump the package.json version in your PR. This version should match the tag in step 5.

git add .
git commit -m "fix: hotfix message"
git push origin hotfix/my-hotfix-branch
  1. Create a pull request from your branch to main
gh pr create -f -B main

  1. Get it reviewed and approved, then squash-merge it into main.

  2. Tag the release

You will need a GPG Key registered with your GitHub User Account to sign the tag with -s. Signed tags get a verified badge on GitHub.com.

git checkout main
git pull origin main
git tag v1.0.0 -m "v1.0.0" -s
git push origin v1.0.0

[!NOTE] We use semantic versioning for our tags.

  1. Create the release
gh release create v1.0.0 --target main -t "v1.0.0"
  1. Back-merge main into dev

Back-merge branches must be prefixed as chore/back-merge-*

git checkout main
git pull origin main
git checkout -b chore/back-merge-v1.0.0
git push origin chore/back-merge-v1.0.0
gh pr create -f -B dev
  1. Get it reviewed and approved, then merge (regular merge, not squash) into dev.

Ignore the This branch is out-of-date with the base branch message along with the Update Branch button. If you press this button, GitHub will create an additional merge commit that we don't need. Simply merge the PR into dev.

[!NOTE] After the back-merge, main will show as "1 behind" of dev. This is expected — the merge commit exists only on dev, but no content has diverged. The branches are in sync.

Further Reading