Pitfall Release Tag Drift

Pitfall: Release tag drift

Affects: GitHub releases, deploy confidence, rollback clarity
Observed: v1.2.10 verification pass

---

What happened

The GitHub release v1.2.10 existed, but main had additional commits after the tag:

fee3ce2 docs: align scope documentation with site.admin model
3d2102f fix: log scope clamping, guard anonymous/read boundary, fix smoke probe

The tag itself pointed at the earlier implementation commit:

v1.2.10 -> ad6ce10 feat: collapse system.admin into site.admin

This means the release artifact and release notes can look current while the tag does not include the newest verified fixes.

Why it matters

Release tags are operational anchors:

• deployment audits use them to identify what is running;
• rollback plans use them to select a known commit;
• GitHub release notes imply the tagged source contains the described fix;
• downstream users download source archives from the tag, not from main.

If fixes land after a tag, do not silently treat the old tag as current.

How to diagnose

Run:

git fetch --tags origin
git rev-list -n 1 v1.2.10
git rev-parse main
git log --oneline v1.2.10..main

If git log --oneline v1.2.10..main prints commits, the tag is behind main.

Correct response

Do not force-move a public tag unless there is explicit operator approval and no consumers rely on it.

Preferred response:

1. Keep the existing tag immutable.
2. Verify the newer commits with CI and live smoke tests.
3. Create the next patch release tag, for example v1.2.11.
4. Document that the new tag includes the post-v1.2.10 fixes.

Release checklist rule

Before publishing a release:

git rev-parse HEAD
git rev-list -n 1 <tag>
git log --oneline <tag>..HEAD

The final command must be empty. If it is not empty, either tag the current commit or create the next patch release.

Related docs

• docs/release-checklist.md
• Release Checklist
• Smoke Tests and Live Verification