Annotate the release tag before moving v1

[MattFisher]

Overview

Fixes the copier update downgrade failure, which is worse than it first looked: publishing 1.8.0 moved v1 onto the same commit as v1.8.0, and every consumer update path is now blocked, not just the scheduled ones.

Root cause

Copier reads a template's version via Template.commit → git describe --tags --always, then parses it with dunamai (copier/_template.py). git describe ranks candidate tags on the same commit by annotation first, then recency. bump-v1.yml creates v1 through the refs API, which makes it lightweight — and publishing a release for a tag that doesn't exist yet (the GitHub UI's default) creates a lightweight tag too. Two lightweight tags tie on annotation, and v1 wins the tiebreak.

So describe answers v1, dunamai reads version 1, and copier refuses any project above 1.0.0:

You are downgrading from 1.7.0 to 1. Downgrades are not supported.

Reproduced against a real consumer checkout. Critically, this is not just the --vcs-ref v1 default the scheduled workflow passes — an explicit --vcs-ref v1.8.0 resolves the same commit and fails identically. There is currently no working update path for any of the four consumers. Copier exits 1, so the scheduled runs fail loudly rather than silently no-op'ing.

This has been broken since 1.6.0, the first release whose tag was created by publishing rather than pushed with git tag -a. Tags v1.0.0 → v1.5.2 are all annotated; v1.6.0, v1.7.0 and v1.8.0 are not. It went unnoticed because nothing ran copier update in that window.

The invariant

Measured on a clone of this repo, all three combinations on one commit:

release tag	v1	git describe --tags
lightweight	lightweight	v1 ❌
annotated	lightweight	v1.8.0 ✅
annotated	annotated	v1 ❌

Both-annotated breaks again because v1 is re-tagged on every release and is therefore always the newer of the two. So the rule is precise: release tag annotated, v1 lightweight. The Move step already guarantees the second half by construction.

What changed

• bump-v1.yml: an Annotate the release tag step that creates a tag object over the released commit and force-updates the ref, when publishing left the tag lightweight. Placed after the existing refusals, so a release that is going to be turned away never has its tag rewritten. Idempotent — it exits early if the tag is already annotated.
• CHANGELOG.md: the invariant documented alongside the other two version-mechanics notes at the top, plus a [1.8.1] section.

Annotating rather than refusing keeps releases publishable straight from the GitHub UI. The rewrite keeps the same target commit, and the release references the tag by name, so the published release is unaffected; it lands seconds after publication, before the tag has realistically been fetched anywhere.

Verification

• End-to-end against a local clone with the release tag annotated and v1 lightweight on the same commit: git describe --tags → v1.8.0, and copier update --defaults --trust --vcs-ref v1 in a real consumer checkout reports Updating to template version 1.8.0, writes _commit: v1.8.0, and applies the basedpyright migration.
• git cat-file -t confirms the two states the step discriminates on: lightweight → commit, annotated → tag.
• Ran bump-v1.yml's changelog gate against the edited file for v1.8.1: PASS.
• Workflow parses as YAML; step order is Refuse to move v1 off main → Require a changelog entry → Annotate the release tag → Move v1. The job already holds contents: write.

Releasing this

Publish v1.8.1 however you like, including straight from the UI — the workflow now repairs the tag itself. That release is what unblocks the four consumers: they land on 1.8.1 rather than 1.8.0, identical bar this fix.

v1.8.0 is left as-is rather than force-pushed over.