Skip to content

docs(contributing): draw pep.rst's release-trigger chain as a Mermaid graph - #963

Merged
JarryShaw merged 1 commit into
mainfrom
docs/719-pep-mermaid-trigger-chain
Oct 1, 2026
Merged

JarryShaw merged 1 commit into
mainfrom
docs/719-pep-mermaid-trigger-chain

Conversation

@JarryShaw

Copy link
Copy Markdown
Owner

Please follow the guide below

What is the purpose of your pull request?

  • docs — documentation only

Description

Part of #719 (docs/source/contributing/pep.rst slice), per the repo owner's ruling there: prefer a Mermaid graph over a paragraph/ASCII diagram where the subject is a flow.

Converted: the .. code-block:: text ASCII chain in "Release Plan" (push to main -> Vendor Update -> Create Release) to a .. mermaid:: flowchart, styled to match the three existing directives in workflows.rst/releasing.rst (flowchart TD, short node IDs, <br/> labels, thick ==> for workflow_run).

Factual fix found while verifying: the old diagram skipped a hop and misattributed a trigger. It said cron-vendor.yml triggers on push to main — but cron-vendor.yml:6-13's own comment says it deliberately carries no push trigger (to avoid double-running Unit Tests' gate job, #715). The real chain is push to main → Unit Tests → Vendor Update → Create Release, verified against cron-vendor.yml, create-release.yml, and unit-tests.yml directly.

Considered and rejected: the "Every publishing job… is gated on" paragraph (per-job if: rationale) and the "Delivery Sequence" wave ordering — both are "why" rationale a diagram can't carry, so left as prose. No other ASCII diagrams exist in the file. Checked unit-tests.yml:58-59 for the 3.10–3.14 matrix claim at pep.rst:552 — accurate, unchanged.

Cross-references :doc:workflows`` rather than duplicating its repository-wide graph.

… graph

Part of #719: convert the ASCII `->` chain in "Release Plan" to a
`.. mermaid::` flowchart, matching the style already established in
workflows.rst and releasing.rst (flowchart TD, short node IDs, `<br/>`
for two-line labels, thick `==>` for `workflow_run` edges).

- The old ASCII diagram skipped a hop and misattributed a trigger: it
  showed `push to main -> Vendor Update`, captioned "which triggers on
  push to main". `cron-vendor.yml:6-13`'s own comment says the opposite
  -- it deliberately carries no `push` trigger, to avoid re-running Unit
  Tests' gate job twice for the same commit (#715). The real chain is
  push to main -> Unit Tests -> Vendor Update -> Create Release, each
  hop after the first a `workflow_run` edge. Verified against
  cron-vendor.yml, create-release.yml and unit-tests.yml directly.
- Cross-referenced :doc:`workflows`, which already draws the
  repository-wide version of this graph, rather than duplicating it.
- Swept the rest of the file for other flow-shaped prose and for drift
  against the three named workflow files; found no other ASCII/text
  diagrams and no other inaccuracies (the per-job `if:` gating
  paragraph and the Python-version test-matrix claim both checked out
  against the current workflow files).
@JarryShaw JarryShaw added docs Pull requests that change documentation only (docs: subject prefix) review: pending No verdict for the current head - never reviewed, or the head moved since the last one labels Oct 1, 2026
@JarryShaw

Copy link
Copy Markdown
Owner Author

GOOD TO GO at 9dd2d62c8 — fable cross-review, first round clean. Different
model from the author (sonnet).

I re-derived its load-bearing claims rather than relaying them:

  • cron-vendor.yml genuinely has no push trigger — only schedule and
    workflow_run on Unit Tests. The old prose was wrong, and it also skipped
    the Unit Tests hop entirely.
  • The citation cron-vendor.yml:6-13 is exact: :5 is the cron entry, :6 the
    first comment line, :13 the last, :14 is workflow_run:.
  • The Mermaid block matches workflows.rst:143-153 node-for-node, and
    sphinxcontrib.mermaid is loaded at docs/source/conf.py:81.
  • releasing.rst:94-101 already described this chain correctly, so pep.rst was
    the odd one out rather than being fixed into disagreement.

No full Sphinx build was run on either side; the structural-subset argument plus
CI's docs leg is what stands behind the directive rendering.

Omitting the Saturday schedule edge is a scoping choice, not a defect — the
paragraph scopes itself to the ordinary-commit path and defers the full graph to
:doc:workflows, which already draws it.

@JarryShaw JarryShaw added review: good-to-go Cross-review at the current head says ready; CI state is separate and removed review: pending No verdict for the current head - never reviewed, or the head moved since the last one labels Oct 1, 2026
@JarryShaw
JarryShaw merged commit a736700 into main Oct 1, 2026
63 checks passed
@JarryShaw
JarryShaw deleted the docs/719-pep-mermaid-trigger-chain branch October 1, 2026 14:58
@JarryShaw JarryShaw removed the review: good-to-go Cross-review at the current head says ready; CI state is separate label Oct 1, 2026
@JarryShaw JarryShaw added this to the 1.5 milestone Oct 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Pull requests that change documentation only (docs: subject prefix)

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

1 participant