Repository navigation
docs(contributing): pep.rst describes the pre-#888 release gating as current #956
Description
docs/source/contributing/pep.rst:861-866 describes the pre-#888 release gating as if it were current. Found by a cross-review on #953; it predates both #953 and #955, so neither introduced it — #955 read past it.
What the page says, present tense:
Every publishing job —
github,tag,pypi,conda— is gated on
startsWith(github.ref_name, 'v') || PCAPKIT_TAG_EXISTS == 'false'. That gate
is why ordinary commits do not publish:Create Releaseruns on each one, but
the tag for the current version already exists, so all four jobs skip.
What .github/workflows/create-release.yml does. Only github carries that gate, at :343. The other three use if: >- blocks keyed on their own artefact, and the in-file comments say so explicitly:
tag—:444, comment at:437: gated on whether the tag exists "rather than onPCAPKIT_TAG_EXISTS"pypi—:522, comment at:511: "this job is already idempotent"conda—:621, comment at:610
So "all four jobs skip" is wrong for three of the four, and the sentence explaining why ordinary commits do not publish is wrong for the same three.
Why it matters beyond accuracy. docs/source/contributing/releasing.rst:110 states the opposite as a prohibition — do not gate a release job on whether the v* tag exists — because the shared guard is what let releases skip silently and still finish green. Two pages in the same directory now contradict each other, and the wrong one is the one that reads as a description of the system.
Fix is to rewrite those two sentences from the workflow as it stands: one job on the tag-exists gate, three on their own evidence. Prose only; no workflow change.
Activity
JarryShaw commentedon Oct 1, 2026
Correction to this issue's own body, before #957 lands. I wrote that
taggates "on whether the tag exists". That is ambiguous and, read naturally, wrong —taggates onPCAPKIT_CONDA_TAG_EXISTS, the Conda tag, not thev*tag. The three evidence-based gates, verbatim fromcreate-release.ymlone87c4b00c:tag:447—PCAPKIT_CONDA_TAG_EXISTS == 'false'pypi:525—PCAPKIT_PYPI_COMPLETE == 'false'conda:625—PCAPKIT_CONDA_COMPLETE == 'false'And the issue understated the defect in a second way. Each of those three also requires
github— andcondaalso requirestag— to have succeeded or skipped rather than failed. The page omitted that guard entirely, and it is the one that stops an upstream skip cascading into a false skip downstream, which is the failure #888 was about.One more thing worth recording:
tests/project/test_release_gates.pyalready pins all of this — 34 tests includingtest_tag_gates_on_its_own_conda_tag_evidenceandtest_evidence_gated_jobs_survive_a_legitimately_skipped_predecessor. So the behaviour was tested and the prose simply disagreed with the tests. A prose sweep that does not consult the tests pinning the same subject will keep missing this class.Fix is up as #957.
docs(contributing): correct pep.rst's release gating description (#956)
docs(contributing): correct pep.rst's release gating description (#956)
docs(contributing): correct pep.rst's release gating description (#956)…