Release Hygiene

What you will learn

• Understand the core purpose of Release Hygiene
• Master the basic usage and common options of Release Hygiene
• Use a small set of Git checks before release to reduce mistakes around tags, branches, and version state.
• Understand key concepts: Why release-time Git mistakes are expensive
• Know when to use this feature and when to avoid it

Start with a problem

Your team has developed some Git habits over time, but you're not sure if they are optimal — or you've just been through an incident caused by a Git mistake and want to avoid repeating it.

Why release-time Git mistakes are expensive

Release Prep

Code frozenTests passedChangelog pendingVersion to bump

→Release Flow

Clean Release

SemVer vX.Y.ZAnnotated tag + signatureChangelog grouped by versionPost-release verification checklist

Release hygiene is not process burden — it's quality assurance. Every release should be a trustworthy event.

A little Git ambiguity during development becomes much more costly at release time. A mistargeted tag, a release from the wrong branch, or a dirty working tree can make future version tracking much harder.

Release hygiene is really about making one thing crystal clear: which exact history produced this release.

1. Confirm branch and commit state first

Start with:

git status
git log --oneline --decorate -5

You want to know:

• whether you are on the intended release branch
• whether the working tree is clean
• whether the most recent commits are really the release candidates

2. Tags should point to deliberate commits

The two common mistakes are:

• tagging the wrong commit
• using inconsistent tag names

A safer pattern is:

git tag -a v1.4.0 -m "Release v1.4.0"
git show v1.4.0

That final git show is important because it confirms exactly where the tag landed.

3. Re-check release scope before publishing

It helps to compare the last release tag to the candidate:

git diff --stat v1.3.0..HEAD

That gives a quick sanity check on:

• whether the change set matches expectations
• whether unrelated work slipped in
• whether the release notes still match the real history

4. Good release history is future-friendly

Releases are not only for today. Later you may need to:

• answer when a bug entered
• compare two releases
• roll back to a known stable point

That is much easier when tags are consistent, explicit, and verifiable.

5. A practical release checklist

Use this as a minimal baseline:

1. verify branch and working tree
2. inspect recent commits
3. confirm release diff scope
4. create a clear annotated tag
5. verify the tag target once more

That is lightweight, but it prevents many avoidable release-history problems.

Try it yourself

1. Practice the release-hygiene command in a test repository and observe state changes before and after
2. Experiment with different options and compare the output differences
3. Simulate a real scenario where you would need to use this, and walk through the full process

Further reading

Keep going on the same topic:

• Release checklist discipline
• Review-Ready History and Safe Push
• Safe Cherry-picks