From 9dd2d62c854010adb754b71c7862222b6a1862c6 Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Thu, 1 Oct 2026 09:35:12 -0400 Subject: [PATCH] docs(contributing): draw pep.rst's release-trigger chain as a Mermaid 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, `
` 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). --- docs/source/contributing/pep.rst | 30 ++++++++++++++++++++++++------ 1 file changed, 24 insertions(+), 6 deletions(-) diff --git a/docs/source/contributing/pep.rst b/docs/source/contributing/pep.rst index 7b86823e9..4f3b39997 100644 --- a/docs/source/contributing/pep.rst +++ b/docs/source/contributing/pep.rst @@ -851,12 +851,30 @@ from the same test. Worth spelling out how that workflow is *reached*, because reading its ``on:`` block alone suggests it is not reachable from an ordinary commit at all — it -lists only ``push`` on ``v*`` tags and a ``workflow_run``. The chain is: - -.. code-block:: text - - push to main -> "Vendor Update" (cron-vendor.yml, which triggers on push to main) - -> "Create Release" (workflow_run, on Vendor Update completing) +lists only ``push`` on ``v*`` tags and a ``workflow_run``. The chain is three +hops, not two: a push to ``main`` triggers **Unit Tests** +(``unit-tests.yml``), whose completion triggers **Vendor Update** +(``cron-vendor.yml``) via ``workflow_run`` -- ``cron-vendor.yml`` carries no +``push`` trigger of its own, deliberately, per its own comment at +``cron-vendor.yml:6-13`` -- and *that* completion triggers **Create Release** +itself. :doc:`workflows` draws the repository-wide version of this graph; +here is just the path that matters for a release: + +.. mermaid:: + + flowchart TD + PUSH["push: main"] + + UT["Unit Tests
unit-tests.yml"] + VU["Vendor Update
cron-vendor.yml"] + CR["Create Release
create-release.yml"] + + PUSH --> UT + UT ==>|workflow_run: completed| VU + VU ==>|workflow_run: completed| CR + + classDef trig fill:none,stroke-dasharray:2 2 + class PUSH trig Every publishing job — ``github``, ``tag``, ``pypi``, ``conda`` — is gated on ``startsWith(github.ref_name, 'v')`` or on evidence that its own target still