docs: document the release procedure - #5
Merged
Merged
Conversation
Publishing is manual from a maintainer's machine, so the steps only existed as knowledge. RELEASING.md writes them down, ordered so the irreversible PyPI upload comes last, and states plainly that a version number can never be reused — only yanked. Covers the two places the version must be bumped (they are not derived from one another), the pre-publication checks, tagging the merge commit so the tag points at reviewed code, verifying the wheel actually ships py.typed, and the recovery path when a release is wrong. Also ships CHANGELOG.md in the sdist, so the release notes travel with the source distribution.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
RELEASING.md, following the decision to keep publishing manual — no CI workflow, no PyPI token stored in the repository.The procedure only existed as knowledge, so this writes it down and orders it so the irreversible step comes last. It states plainly that a PyPI version number can never be reused, even after deletion — only yanked — and gives the recovery path when a release turns out to be wrong.
Points it captures that are easy to get wrong:
pyproject.tomland__init__.py) which are not derived from one another, so a mismatch only shows up after publication.py.typed: the package advertisesTyping :: Typed, and without that file type checkers silently ignore every annotation.Every command in the document was run against the 0.2.0 artifacts:
uv build,uvx twine check(both distributions PASSED), thepy.typedcheck, and the isolated install-and-import.Also ships
CHANGELOG.mdin the sdist, so the release notes travel with the source distribution, and links the document from the README.Tag
v0.2.0and the GitHub release are already created, with both artifacts attached. The PyPI upload is left to you: it is irreversible and needs your token.