The Support Scenario

Most of the time, your workflow is simple: you build features, merge them to main, and when you're ready, you tag a commit on main as a new release. Done. If that tagged version is stable and passes all its checks, you can ship it directly.

But what happens when it's not that simple?

• What if you need to run a long stabilization phase (QA, UAT) but can't afford to freeze development on main?
• What if a critical bug is found in production a month later, and you need to patch it without shipping all the new, unrelated features from main?
• What if you froze a version on main a few days but you've just been asked to ship just one more feature? (I know, pure fantasy)

This is where the support branch becomes your most important tool. It's not something you have to create for every release, but it's essential when you need it. Think of it as a support branch: a clean, isolated copy of your release that allows you to apply fixes and patches safely.

Naming Convention: support/

We will use the support/ prefix for these branches. While release/ is common, I believe it inaccurately describes the branch's long-term role. Its job is to support a version in production, not just to release it. The support/ prefix better conveys the branch’s extended lifecycle and helps prevent accidental deletion by making its purpose explicit.

That said, if you prefer release/, feel free to stick with it.

This section covers the two primary scenarios for using a support branch.

1. Pre-release Stabilization: Creating a support branch to harden a new version before launch.
2. Post-release Hotfixing: Using an existing support branch to patch a version already in production.

A critical bug (GG-21) was found in version 1.1.0, which is live in production. Meanwhile, development for 1.2.0 is already underway on main.

Our goal is to create and ship version 1.1.1 with only the fix for GG-2.

Step 1: Check Out the Support Branch

First, find the support branch corresponding to the version in production. This is where your support/ naming convention pays off.

# 1. Ditch whatever you're doing and get to the right support line
git checkout support/1.1

# 2. Make sure you have the latest version of it
git pull

You are now in a clean environment that perfectly mirrors the 1.1.0 production code.

Step 2: Create the Hotfix Branch

Even in an emergency, we follow the rules. Isolate your work in a dedicated branch. This ensures you're only introducing the intended fix.

# Branch from the support branch, not main!
git checkout -b hotfix/GG-21_critical-prod-bug

From here, the process is identical to the standard feature workflow.

Step 3: Fix the Bug and Merge

Make your code changes, commit them with a proper fix: message, and open a pull request.

Crucially, the target of this PR is support/1.1, NOT main.

Once your fix is reviewed and merged, the support/1.1 branch contains the code for what will become version 1.1.1.

Step 4: Tag the merged Hotfix

With the fix merged, it's time to create the official hotfix release. You'll tag the merge commit on the support/1.1 branch, incrementing the patch version number.

# 1. Get on the support branch and make sure it's up-to-date
git checkout support/1.1
git pull

# 2. Create the annotated tag
git tag -a 1.1.1 -m "Version 1.1.1: Critical hotfix for feature GG-2"

# 3. Push the tag to the remote to make it official
git push origin 1.1.1

You can now deploy version 1.1.1. The fire is out. But you're not out of the woods yet.

Step 5: Port the Fix to main (Don't You Dare Forget This)

I'm serious. This is the most commonly forgotten step, and it will come back to haunt you (and by it, I mean your Product Owner).

The bug you fixed in production still exists on main. If you forget to port your fix, it will magically reappear in the next release (1.2.0), and you'll look like a fool.

The cleanest way to get the fix into main is with git cherry-pick.

# 1. Go back to main
git checkout main
git pull

# 2. Create a bugfix branch to carry the fix
git checkout -b bugfix/GG-21_port-hotfix-to-main

# 3. Find the commit hash of your hotfix
#    (Look in the git log of support/1.1 or the merged PR)
git cherry-pick <commit-hash-of-the-hotfix>

# 4. Push and open a PR to merge this into main
git push -u origin bugfix/GG-21_port-hotfix-to-main

By cherry-picking, you apply only the hotfix commit onto main, without bringing any other history from the release branch. Once it's merged, you have truly, finally fixed the bug everywhere.

Now you can go get a coffee. You've earned it.

What's next?

Keep this support/1.1 branch. DON'T remove it. It will come in handy if you need to fix it further more (or ... Add some forgotten features 🤫).

This branch will actively behave like the new main for your 1.1.x versions.