Skip to content

release: 3.0.1; publish from the tag with README links pinned to it - #19

Merged
Akinzou merged 1 commit into
masterfrom
release/3.0.1
Nov 9, 2026
Merged

Akinzou merged 1 commit into
masterfrom
release/3.0.1

Conversation

@Akinzou

@Akinzou Akinzou commented Nov 9, 2026

Copy link
Copy Markdown
Owner

What

  • Release 3.0.1. It ships the README from docs: README with contents and ADR index; log a failed left-open check #18 and the magic_scope fix: a failed left-open check now logs a warning instead of vanishing.
  • README links on PyPI are pinned to the release (ADR 0012).
    • The README in git keeps blob/master links.
    • The publish job runs scripts/pin_readme_links.py, which rewrites them to v<version>.
  • Publishing refuses to run when:
    • it isn't dispatched from refs/tags/v<version>;
    • the tag isn't on master;
    • the tagged commit has no successful ci.yml run;
    • a file or folder link still names another ref.

Why at build time and not in git

If blob/v3.0.1 were written into git, every document added after the last tag (the next ADR, say) would 404 from master's README until the next release.

Also

  • mypy now covers scripts/.
  • The publish job runs twine check --strict.
  • The upload no longer uses --skip-existing: a re-run for a version already on PyPI fails instead of finishing green with nothing uploaded.
  • Checkout no longer persists credentials.
  • The Changelog Project-URL stays on master on purpose (ADR 0012).

Verification

  • Local: ruff, ruff format, mypy --strict (32 files), and pytest (383 passed, 9 skipped).
  • File-length check passes.
  • An isolated copy was pinned to refs/tags/v3.0.1 and built:
    • 30 links pinned, no /master left in the shipped README;
    • twine check --strict passed;
    • refs/heads/master and refs/heads/v3.0.1 are refused.
  • The CI-run API query was checked against the master head (1 run) and a fake SHA (0 runs).
  • /code-review high: 4 rounds.
    • Fixed: everything that could let master links reach PyPI silently, a publish from something other than the tag, or docs that contradict the code.
    • After round 4, only one-line config changes and docs wording were left; the full gate passed again on that state.

Named debt (MEDIUM or lower, deliberate)

  • The pin regex and the check regex are separate.
    • Some URL forms are refused instead of pinned: http://, www., raw/master, a raw link written as refs/tags/..., and a bare URL ending in a period.
    • That fails loudly and blocks the release; it never ships a bad page. The current README has none of these forms.
    • Merging the two into one regex is a refactor for later.
  • compare/...master and releases/latest are not checked. The README has none; ADR 0012 says so.
  • The pyproject version is read with a regex because tomllib needs Python 3.11 and the tests run on 3.10. A different TOML spelling fails loudly.
  • The test loader is duplicated between two script tests.
  • The publish job does not fail fast: a wrong ref is refused only after checkout and setup.

PyPI keeps each release's README forever, and 3.0.0's links said blob/master,
so its page drifts with master. scripts/pin_readme_links.py rewrites the
README's master links to v<version> in the publish job and refuses any other
ref, a tag off master, a commit without a green ci.yml run, or a file link
left on another ref (ADR 0012).

Pinning at build time instead of in git, because pinned links in git would
404 for every document added after the last tag.

Also: mypy covers scripts/, twine check --strict and no --skip-existing in
the publish job, checkout without persisted credentials.
@Akinzou
Akinzou merged commit 0ba2932 into master Nov 9, 2026
8 checks passed
@Akinzou
Akinzou deleted the release/3.0.1 branch November 9, 2026 13:29
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