Make RELEASE.md describe the release we actually run

[eman]

Two places where the documented process contradicts the tooling. Both have already cost us something on 9.3.1.

1. Two things wanted to write the changelog heading

RELEASE.md:114 said to edit CHANGELOG.rst and add Version X.Y.Z (YYYY-MM-DD) by hand, then commit it, then run make version-bump. But bump_version.py:update_changelog() inserts that heading itself and commit_changelog() commits it.

Follow the document and you get a duplicate heading and a redundant commit — which is what happened cutting 9.3.1. It is worse than cosmetic: scripts/extract_changelog.py parses that heading to build the GitHub release notes, so a duplicate produces wrong release notes.

The section now says to write entries under Unreleased only, and lists what the script actually does — including the clean-working-directory and up-to-date-with-remote checks that decide whether it runs at all, neither of which was documented.

2. The manual publish path is obsolete

Sections 6–8, the pre-release checklist, and the command table all documented make publish / twine upload with TWINE_USERNAME and TWINE_PASSWORD. That is not how this project publishes: release.yml uses pypa/gh-action-pypi-publish with PyPI trusted publishing, triggered by a v* tag.

A maintainer following the document after pushing a tag would attempt to upload a version PyPI had already accepted. Replaced with:

• what the workflow does, job by job, and how to watch it
• an explicit Do Not Publish By Hand, with the Makefile targets kept but labelled emergency-only
• Publishing Credentials: there are none to set up, and why

make release's own output was also telling you to run make publish when it finished — that now points at the tag flow. Its name is misleading too, so the Quick Release section opens by saying it releases nothing.

Also

• Recovery for a release that fails after the tag is pushed. The tag is the trigger, so a red pre-release check leaves a tag behind pointing at a commit that was never released. That is exactly what 9.3.1 needed and it was not written down anywhere — including the check for whether the publish job got far enough that the version is burned.
• CI section no longer suggests "consider setting up CI/CD" for CI that has existed for a while. It lists the actual jobs, and records why Test without CLI extras (Run the tests once without the CLI extras #128) exists.

Verified: no broken intra-document anchors, no surviving references to the manual upload flow, make release's new output reads correctly.

Docs and one Makefile echo only — no library code changes.

[Copilot]

🟡 Changes recommended

RELEASE.md currently documents a CI job (“Test without CLI extras”) that is not present in ci.yml (PR #128 is still open), and a couple of script-behavior details are slightly overstated.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Updates the project’s release documentation (and make release messaging) to match the actual automated tag-triggered GitHub Actions publishing flow, reducing the risk of maintainers following obsolete/manual steps.

Changes:

• Clarifies that make release is a local readiness check/build step and does not publish.
• Updates version bump guidance to reflect that the bump script owns the changelog heading/commit/tag.
• Replaces obsolete manual PyPI upload instructions with the CI-driven trusted publishing workflow and recovery guidance.

File summaries

File	Description
RELEASE.md	Aligns the documented release process with the current bump script + tag-triggered release.yml workflow, and updates CI/publishing guidance.
Makefile	Adjusts release target description/output to avoid implying manual publishing and to point at the tag-based release flow.

Review details

Suppressed comments (1)

RELEASE.md:391

• This paragraph describes the rationale for a "Test without CLI extras" job, but that job is not present in .github/workflows/ci.yml in the current codebase (PR #128 is still open). Either add the job to CI in this PR, or reword this section to describe it as a proposed/pending improvement instead of an existing workflow.

`Test without CLI extras` exists because `tox` installs the `cli` extra while
`release.yml` does not. Without it, a test module that imports `click` outside
its `ImportError` guard passes every pull request and fails only once the
release tag has been pushed.

• Files reviewed: 2/2 changed files
• Comments generated: 4
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[eman]

Fixed in f7aacf5 — the list now says it refuses to run when the working directory is dirty or the branch is behind its upstream, and that being ahead or having no upstream only warns.

[eman]

Fixed in f7aacf5, at the source: bump_version.py no longer prints the make publish-test / make publish next steps. It now says to push the commit and the tag, and that the tag triggers release.yml — so there is nothing left for the document to warn about.

[eman]

Fixed in f7aacf5 — the warning now says extract_changelog.py finds no matching section and the notes fall back to the bare line Release X.Y.Z, rather than being empty.

[eman]

Resolved: #128 merged as 8ec21f4, so Test without CLI extras is in ci.yml on main. This branch has merged main, so the table matches the workflow. (The install line is now -e ".[testing]" to match what the job and release.yml actually run.)