[dimitri-yatsenko]

Releases become annotated tags whose messages are the release notes, and the changelog file is removed. The history lives in the tags' messages; the GitHub releases mirror them.

Releases from annotated tags

A release is an annotated tag vX.Y.Z on master, created with git tag -a vX.Y.Z --cleanup=verbatim -F notes.md. Pushing it runs the new Release workflow (.github/workflows/release.yaml):

1. Check the tag (.github/scripts/check_release_tag.sh). It fetches the tag object itself, because checkout can store an annotated tag as a lightweight ref.
   • It fails on a lightweight tag, and the error gives the git tag -a command.
   • It fails on a tag whose commit is not on master.
   • It stops, without publishing, on a tag whose message has a Retroactive: line. Such a tag records a past release.
2. Run the lint and test workflows as the gate. They gain a workflow_call trigger for this.
3. Build the package at the tag. hatch-vcs takes the version from the tag, and a step checks that the wheel and sdist carry it.
4. Publish with twine, using the same secrets as before.
5. Create the GitHub release: gh release create "$TAG" --verify-tag --notes-file <the tag's message> dist/*. This replaces the archived upload-release-asset action.
6. Post to Slack, as before.

Running the workflow by hand from a tag publishes it to TestPyPI. With testpypi unchecked, it repeats a release that failed partway.

This replaces release-drafter: the Manual Draft Release workflow, release_drafter.yaml, and the workflow that published a release once its draft was published. Labels no longer produce the notes, but a pull request's title must still state its user-visible change, because the notes are written from the titles. RELEASE_MEMO.md describes how to cut a release, and CONTRIBUTING.md points to it.

The history in the tags

Every past release that has notes has been re-tagged as an annotated tag on the same commit, with those notes as its message:

• 0.3.2–0.14.3 take their section of CHANGELOG-archive.md (47 versions);
• later versions take the GitHub release body (24 versions);
• v0.11.2 also takes its GitHub release body. The archive's 0.11.2 entry (the pyparsing fix of Jul 25, 2019) shipped as 0.11.3, while the v0.11.2 tag marks the build published to PyPI on 2019-04-13, and its release says so.

A version with no notes anywhere keeps its tag as it is. That applies to v0.4.8, v0.6.1, v0.7.1, v0.8.1, v0.8.2 and v0.10.2.

A re-tagged message ends like this:

Released: 2024-09-23
Retroactive: re-tagged 2026-10-20 from CHANGELOG-archive.md at a00b89f5544e (was a lightweight tag)

No tag moved to another commit, so pip install git+...@vX.Y.Z, the versions hatch-vcs derives, and the GitHub releases are unaffected.

If your clone already has these tags, a plain git fetch --tags reports "would clobber existing tag" for them. Run git fetch --force --tags once.

With the history in the tags, CHANGELOG-archive.md is removed. Nothing else refers to it or to release-drafter.

Checks

• actionlint, with shellcheck, passes on the new and changed workflows. shellcheck passes on the check script.

• The check script was run on a scratch repository against five tags:

  Tag	Result
  annotated, on master	publish
  lightweight	fail, with the git tag -a command
  retroactive	stop without publishing
  annotated, off master	fail
  not vX.Y.Z	fail

  A clone that stores the annotated tag as a lightweight ref is still read as annotated.

Supersedes #1609.