Repository navigation
docs: diagrams, release gate on the docs site; release 3.0.2 - #22
Merged
Merged
Conversation
…aits for the site Diagrams: retries and magic-number scope in the README (and so the user guide); layers, ports, the request flow and concurrency in the architecture page (ADR 0014). - overrides/main.html pins Mermaid 11.17.2 with a Subresource Integrity hash; Material uses it instead of fetching the newest 11.x. - scripts/check_diagrams.py renders every diagram in headless Chrome with that file and hash, in its own docs.yml job; the deploy waits for it. It also fails on a Mermaid fence written in a form it cannot extract. - scripts/replace_readme_diagrams.py swaps each diagram, at publish, for a link to its README section on GitHub, before the links are pinned to the tag. It refuses a diagram that would swallow other text. - scripts/mermaid_fences.py is the one definition both scripts use. - python-publish.yml refuses a release until the docs.yml deploy job succeeded for the tagged commit, so the site PyPI links already shows the release. - Tests import scripts/ through pytest's pythonpath instead of four copies of an importlib loader. Chose a pinned URL with an integrity hash over a vendored copy because it pins the file without 3 MB in the repository. Chose one shared fence definition over a copy per script because two copies would let CI pass a README the publish then refuses.
Documentation only: the library code is unchanged since 3.0.1 apart from docstrings (checked by comparing each module's AST without them).
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.
What
open_positionrequest flow and concurrency on the architecture page. See ADR 0014.overrides/main.htmlloads Mermaid 11.17.2 with asha384integrity hash (cross-checked against jsDelivr's hash of the npm file). Material uses it instead of fetching the newest 11.x.scripts/check_diagrams.py, headless Chrome with sandbox) with the same file and hash, in its owndocs.ymljob. The deploy waits for it. It also fails on a Mermaid fence written in a form it cannot extract, and when Mermaid never loaded.scripts/replace_readme_diagrams.pyswaps each diagram for a link to its README section on GitHub. The pin step then pins it to the tag, so a release links its own diagrams. It refuses a diagram that would swallow other text.python-publish.ymlrefuses to publish until thedocs.ymldeploy job succeeded for the tagged commit, so the site linked from PyPI already shows the release.src/changes are docstrings only, checked by comparing each module's AST with docstrings removed.Verification
check_file_length.py,mkdocs build --strict,check_diagrams.py(6 diagrams render).refs/tags/v3.0.2: diagrams replaced (2), links pinned (34, including#retriesand#magic-numbers-whose-trades-a-call-touches),twine check --strictpasses.;in a sequence label, a~~~fence and a wrong integrity hash each failcheck_diagrams.py.mermaid@11.17.2(checked from the browser's resource list).Review
/code-review high, four rounds, about 40 findings. Fixed: every finding that would ship something wrong to readers, PyPI or the release, including:Not fixed, with the reason:
check_diagrams.pymay hang on Windows when Edge outlives a timeout. This only affects local runs; CI uses Chrome on Linux.Static analysis
Semgrep: 0 findings at ERROR and 0 at WARNING (97 + 98 rules).