docs: make the README work off GitHub and show what differs - #174
Merged
Conversation
The README is the package's long description, and PyPI resolves a relative link against pypi.org rather than the repository — so all 31 of them, the whole of docs/ plus CONTRIBUTING.md, SECURITY.md, the licence and the examples, answered 404 for a reader arriving on the package page, which is where the new Homepage link now sends people. Every link is absolute and documentation points at the published site instead of raw Markdown, which also spares a GitHub reader the tab syntax that only renders once built. The page also never demonstrated the two reasons to choose this breaker: the only configured example set a failure rate and a minimum call count, the two knobs every other library has. The quickstart now configures the slow-call thresholds and guards an async callable with the same instance, a new section shows Redis-backed shared state, the rollout section drops the paragraph that restated the states guide, and a state-machine diagram opens the page. tests/test_readme.py fails the build on a relative link, on a documentation url with no page behind it, on a repository url with no file behind it, and on an anchor with no matching heading.
Contributor
|
Note Currently processing new changes in this PR. This may take a few minutes, please wait... ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (3)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
Contributor
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Owner
Author
|
@coderabbitai help |
6 tasks
bagowix
added a commit
that referenced
this pull request
Aug 17, 2026
## Summary Prepare the `2.6.1` patch release. * Bump the package version from `2.6.0` to `2.6.1`. * Move the current `[Unreleased]` changelog entries into `[2.6.1] - 2026-08-17`. * Update changelog comparison links and the comparison-page release version. * Regenerate `docs/llms-full.txt`. Patch, not minor: nothing under `interlock/` changed since v2.6.0 — the release carries documentation and packaging metadata only (#166, #173, #174), and griffe reports the `VERSION` attribute as the sole public difference. It exists because a package page keeps the description and the project urls of the version that was uploaded, so none of that work is visible where it was aimed. pypi.org currently serves the README whose 31 relative links answer 404 there, and a `Homepage` pointing at the repository rather than at the documentation. Checked on the built wheel: `Homepage` → the documentation site, 0 relative links in the long description, state-machine diagram embedded. ## Checklist * [x] Tests added or updated (suite stays at 100% coverage) * [x] `uv run ruff format --check` and `uv run ruff check` pass * [x] `uv run mypy`, `uv run pyright` and `uv run pyrefly check` pass * [x] Docs updated (`docs/`) for user-facing changes * [x] `CHANGELOG.md` `[Unreleased]` updated * [x] Commits follow Conventional Commits Additional release checks: the package build passes (`interlock_cb-2.6.1`), `twine check` PASSED on both artefacts, and griffe reports only the expected public `VERSION` change (`2.6.0` → `2.6.1`). One timing note for tagging: GitHub is currently returning `No server is currently available to service your request` on parts of its API — CodeQL and Scorecard failed that way on #174 and on `main`, at the Initialize step rather than in analysis. Worth having those green before pushing the tag, so the publish job does not meet the same outage. ## Related issues #166 #173 #174
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
1 participant
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.
Summary
The README is the package's long description, and PyPI resolves a relative link against
pypi.orgrather than the repository. All 31 relative links — the whole ofdocs/,CONTRIBUTING.md,SECURITY.md, the licence, the examples — answered 404 for anyone arriving on the package page, which is exactly where the newHomepagelink sends people. Verified withreadme_renderer[md], the renderer warehouse itself uses: 31 relative links before, 0 after.Every link is now absolute, and documentation points at the published site instead of raw Markdown — which also spares a GitHub reader the
=== "uv"tab syntax that only renders once built.While in there, the page also never demonstrated the two reasons to pick this breaker over the established ones. Its only configured example set a failure rate and a minimum call count, the two knobs every other library has:
asynccallable, so "sync and async in one class" is shown rather than asserted;docs/img/state-machine.svgopens the page: CLOSED / OPEN / HALF_OPEN with the condition on every edge, including the slow-call rate. One asset, no external fonts, no theme-dependent colours, so it renders identically on GitHub, on PyPI and in either colour scheme.tests/test_readme.pykeeps it that way: it fails on a relative link, on a documentation url with no page behind it, on a repository url with no file behind it, and on an anchor with no matching heading. Each guard was confirmed to fail on a deliberately broken README before being kept.Note: the diagram is embedded through a
raw.githubusercontent.com/.../main/...url, so it renders as a broken image in this PR preview and starts working the moment the branch lands onmain. Relative paths are not an option — they are the bug this PR fixes.Verified locally: every code block in the README executes as written (quickstart, rollout transport, Redis storage, httpx2 transport, pipeline),
uv build+twine checkPASSED,uv run pytest --cov776 passed at 100%, ruff/mypy/pyright/pyrefly clean.Checklist
uv run ruff format --checkanduv run ruff checkpassuv run mypy,uv run pyrightanduv run pyrefly checkpassdocs/) for user-facing changesCHANGELOG.md[Unreleased]updatedRelated issues
Added
Fixed
Changed