Skip to content

docs(contributing): pep.rst describes the pre-#888 release gating as current #956

Description

@JarryShaw

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 Release runs 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 on PCAPKIT_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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugIssues reporting a defect (set by the bug report template; a default, not an assessment)docsPull requests that change documentation only (docs: subject prefix)

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions