docs(contributing): correct releasing.rst's cascade guard (#958)

[JarryShaw]

Please follow the guide below

• Searched for similar pull requests
• Followed the coding style (make pylint, make mypy, make isort)
• make test passes, and a test case covers the change
• Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible — N/A — documentation prose only, no library behaviour change

What is the purpose of your pull request?

• fix — corrects a defect
• feat — adds a feature
• perf — changes performance, not behaviour
• refactor — changes neither behaviour nor performance
• test — tests only
• docs — documentation only
• ci — workflows or build tooling
• chore — anything else

---

Description of your pull request and other information

Closes #958. The companion to #957. On main today this is the only page that states the cascade guard at all, and it states it wrongly — pep.rst does not mention it, and the corrected version of that page lives only in unmerged #957.

What was wrong. releasing.rst generalised the sibling workflows' guard to the three publishing jobs:

The three jobs here do the same for each of their own direct dependencies: !cancelled() && needs.<job>.result != 'failure'.

No job in create-release.yml uses that spelling. The only two occurrences in the file are comments explaining why it is not used (:119, :124-128). What tag, pypi and conda actually use, for github and — for conda — tag:

!cancelled() && (needs.<job>.result == 'success' || needs.<job>.result == 'skipped')

Why it matters rather than being a typo. The two spellings differ only when a predecessor's own result is cancelled, and that is the case the real spelling exists for. With tag cancelled and the run itself not cancelled, != 'failure' evaluates true and conda runs, into actions/checkout with ref: conda-<version>+0 for a tag tag never pushed — trading a clean skip for a checkout failure. So the documented guard would have reintroduced exactly what the real one prevents.

A second over-generalisation, which the original sentence also carried. "each of their own direct dependencies" is false for version_check, which is a direct dependency of all three and is required to have strictly succeeded, with no || 'skipped' (:445, :523, :622). It now has its own sentence, with the reason: it produces the evidence the gates read, so a skipped or cancelled version_check leaves them nothing to decide on.

Untouched and correct: the first half of the paragraph. cron-vendor.yml, deploy-pages.yml and cron-conda.yml genuinely do use != 'failure' for needs.unit-tests.result. Only the sentence generalising that to the publishing jobs was wrong.

Verification. tests/project/test_release_gates.py:624 already asserts != 'failure' must not appear in these conditions — so the behaviour was pinned and only the prose disagreed. 34 tests, 23 subtests, re-derived as 34 tests, OK under plain unittest. grep -rln "releasing.rst" tests/ is empty, so no test pins this page's prose. The edited block parses under docutils.

A grep trap for anyone re-checking this: grep "!= 'failure'" docs/source/contributing/releasing.rst on main returns only :171, which is the correct occurrence. The wrong one wrapped across a line break, so a single-line grep missed it entirely.

Not verified: no sphinx-build was run. No workflow file was changed.

[JarryShaw]

GOOD TO GO at fc5b5c53c — fable cross-review, first round clean. Different model from the author and from #957's reviewer.

It did the two things I most wanted and neither was in the diff's own claims.

It enumerated rather than accepted "differ only when cancelled". needs.<job>.result takes exactly {success, failure, cancelled, skipped}; the two spellings agree on success T/T, failure F/F, skipped T/T, and diverge only on cancelled T/F. On a whole-run cancellation the shared !cancelled() prefix makes both false, so there is no second divergence. "Only" survives.

It checked the half of the paragraph this change does not touch, which nobody had: all three siblings do open with exactly !cancelled() && needs.unit-tests.result != 'failure' && — cron-vendor.yml:68, deploy-pages.yml:66, cron-conda.yml:64. So the untouched sentence is correct and the fix is confined to the right place.

It also derived the conda/tag direction independently of pep.rst — the clause that was inverted on the sibling page — and found the checkout real: ref: conda-${{ … PCAPKIT_VERSION }}+0 at :642, with tag being what pushes that tag. And it noted what the pinning test does not cover: there is no version_check.result assertion anywhere in test_release_gates.py, so the new version_check paragraph rests on the workflow file rather than on a test.

Three things it raised that I am acting on separately rather than here:

• A correction to my own PR description, now fixed. I wrote that main ships one page stating this guard correctly and one wrongly. It does not: main's pep.rst does not state the cascade guard at all — I verified, the only skipped hit on that page is unrelated prose at :310. The correct version exists only in unmerged docs(contributing): correct pep.rst's release gating description (#956) #957, so my sentence described the post-docs(contributing): correct pep.rst's release gating description (#956) #957 state.
• The workflow's own comment carries the very over-generalisation this change removes. create-release.yml:121-124 says the three jobs "do the same for each of their own direct dependencies, but spelled as" the equality pair — which is false for version_check, exactly as the prose was. After this merges, the docs describe the workflow more accurately than the workflow describes itself. Filing it.
• "unit-tests's other callers" in the untouched sentence is loose, since the three depend on unit-tests only transitively. Pre-existing and outside this diff; leaving it.

One more non-blocking point worth keeping: the version_check strictness has a sharper consequence than the paragraph gives. On a v* tag push the startsWith clause short-circuits the evidence check, so version_check.result == 'success' becomes the only thing transitively binding the unit-tests gate. True as written, just not the strongest statement of it.

Unverified by anyone: no sphinx-build, on this page or pep.rst.

Labelled review: good-to-go. CI still running, so not ready to merge — and the merge is yours.