Hotfix Releases

The Hook (The "Byte-Sized" Intro)

Production is broken. Users are affected. The latest main has 20 new commits you haven't tested. You can't deploy main — too risky. You need a hotfix: a tiny, surgical patch based on the last known-good release tag. Branch from the tag, fix the bug, tag a new patch version, deploy. Back online in minutes, not hours.

📖 What is a Hotfix Release?

A hotfix release is a small, fast patch for a critical production issue. It branches from the last release tag (not from main), applies only the minimal fix, and creates a new patch version.

Conceptual Clarity

Hotfix workflow:

Step	Action	Command
1. Branch from release tag	Create hotfix branch	`git checkout -b hotfix/v1.2.1 v1.2.0`
2. Apply the fix	Minimal code change	`git commit -m "fix: patch auth crash"`
3. Test	Run targeted tests	`npm test`
4. Tag the patch	Create patch version	`git tag -a v1.2.1 -m "Hotfix"`
5. Deploy	Push and deploy	`git push origin v1.2.1`
6. Merge back	Port fix to main	`git switch main && git merge hotfix/v1.2.1`

Hotfix vs regular release:

Aspect	Regular Release	Hotfix
Branch from	`main`	Last release tag
Scope	Multiple features/fixes	Single urgent fix
Timeline	Planned	Emergency
Version bump	MINOR or MAJOR	PATCH
Testing	Full regression	Targeted

Real-Life Analogy

A hotfix is like an emergency plumbing repair. You don't renovate the whole bathroom — you just fix the leak. You use the materials on hand (the last released version), patch the problem, and get back to normal. The full renovation (next release) continues separately.

Visual Architecture

gitGraph commit id: "A" commit id: "B" tag: "v1.2.0" branch hotfix/v1.2.1 commit id: "Fix bug" commit id: "v1.2.1" tag: "v1.2.1" checkout main commit id: "C (new feature)" commit id: "D (new feature)" merge hotfix/v1.2.1

Why It Matters

Speed: Fix critical issues in minutes without shipping untested features.
Safety: Based on the last released (tested, stable) version.
Minimal risk: Only the fix changes — no new features, no surprises.
Clean history: Merge back preserves the fix in future releases.

Code

bash

# ─── Emergency hotfix workflow ───

# 1. Branch from the last release tag
git checkout -b hotfix/v1.2.1 v1.2.0

# 2. Apply the minimal fix
# ... edit the affected file ...
git add src/auth.js
git commit -m "fix: resolve authentication crash on expired tokens"

# 3. Run targeted tests
npm test -- --grep "auth"

# 4. Tag the patch version
git tag -a v1.2.1 -m "Hotfix: auth crash on expired tokens"

# 5. Push (triggers CI/CD)
git push origin hotfix/v1.2.1 --follow-tags

# 6. Merge fix back to main
git switch main
git pull origin main
git merge hotfix/v1.2.1
git push origin main

# 7. Clean up
git branch -d hotfix/v1.2.1
git push origin --delete hotfix/v1.2.1

Key Takeaways

Hotfixes branch from the last release tag, not from main.
Apply only the minimal fix — no extra features or cleanups.
Tag as a PATCH version (e.g., v1.2.0 → v1.2.1).
Always merge the fix back to main so it's not lost.

Interview Prep

Q: Why should hotfixes branch from a release tag instead of main? A: Because main may contain untested commits that aren't ready for production. Branching from the last release tag ensures the hotfix is based on the exact code currently in production, minimizing risk.
Q: What version bump type does a hotfix use? A: PATCH (e.g., v1.2.0 → v1.2.1). Hotfixes are backward-compatible bug fixes by definition, which maps to a PATCH increment in Semantic Versioning.
Q: Why must hotfixes be merged back to main? A: If the fix isn't merged back, the next release from main will reintroduce the bug. Merging ensures the fix is included in all future releases.