Skip to content

docs: document the release procedure - #5

Merged
sebartyr merged 1 commit into
mainfrom
docs/releasing
Aug 18, 2026
Merged

docs: document the release procedure#5
sebartyr merged 1 commit into
mainfrom
docs/releasing

Conversation

@sebartyr

Copy link
Copy Markdown
Member

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:

  • The version lives in two places (pyproject.toml and __init__.py) which are not derived from one another, so a mismatch only shows up after publication.
  • Tag the merge commit, so the tag points at reviewed code.
  • Verify the wheel actually ships py.typed: the package advertises Typing :: Typed, and without that file type checkers silently ignore every annotation.
  • Install the built artifact in a throwaway environment and import it, which catches a broken package that still builds fine.

Every command in the document was run against the 0.2.0 artifacts: uv build, uvx twine check (both distributions PASSED), the py.typed check, and the isolated install-and-import.

Also ships CHANGELOG.md in the sdist, so the release notes travel with the source distribution, and links the document from the README.

Tag v0.2.0 and the GitHub release are already created, with both artifacts attached. The PyPI upload is left to you: it is irreversible and needs your token.

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.
@sebartyr
sebartyr merged commit e3779c6 into main Aug 18, 2026
4 checks passed
@sebartyr
sebartyr deleted the docs/releasing branch August 18, 2026 13:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant