Release Hygiene

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.