ADR 0012: Publish from the tag and pin the README's links there¶
- Status: accepted (3.0.1). Asked for by the package owner on 2026-11-09.
Context¶
PyPI renders the README of each release and keeps it forever. Relative links
break there, so the README links other documents with absolute GitHub URLs.
In 3.0.0 those URLs said blob/master: the 3.0.0 page on PyPI shows whatever
master holds today, which may describe a later release.
Decision¶
- The README in git keeps
blob/master/tree/masterlinks. scripts/pin_readme_links.pyruns in the publish workflow before the build and rewrites them to the tagv<version>, takingversionfrom the[project]table of pyproject.toml.- It refuses to run unless the workflow was dispatched from
refs/tags/v<version>(gh workflow run python-publish.yml --ref vX.Y.Z), so the package and the documents it links are the same tree. - The workflow refuses a tag that is not on master, or whose commit has no
successful
ci.ymlrun (an--adminmerge skips the PR checks). - It fails, and the release does not publish, when it finds nothing to pin or
when a
blob,tree,raw,blame,edit,commits,archive,raw.githubusercontent.comor.git@link to this repository names a ref other than the tag. Other forms (compare/...master,releases/latest) are not checked; the README has none. A bare link to the repository (the CI badge, the home page) is not a document and stays as it is. - The upload does not skip files already on PyPI: a re-run for a published version fails instead of finishing green with nothing uploaded.
Rejected: publishing on tag push. gh release create pushes the tag, so the
upload would stop being a separate, deliberate step; with manual dispatch a
wrong --ref fails loudly instead.
Rejected: writing blob/vX.Y.Z into the README in git. A document added
after the last tag (the next ADR, say) would 404 from master's README until
the next release, and every release would need a sweep of the links.
Consequences¶
- What PyPI shows for a release no longer changes after it ships.
- The README inside the sdist differs from git: only those links.
- Publishing from master now fails. The procedure: merge the release PR,
wait for the master CI run to finish green, tag the merge commit, then
dispatch the workflow with
--ref vX.Y.Z. - The
ChangelogURL in pyproject.toml stays on master on purpose: the PyPI sidebar should lead to the newest CHANGELOG, which also lists every fix released after the version a reader is looking at. - 3.0.0 on PyPI keeps its master links; PyPI does not allow re-uploading it.