Skip to content

docs(contributing): releasing.rst documents the cascade guard with the rejected spelling #958

Description

@JarryShaw

docs/source/contributing/releasing.rst:176-177 states the cascade guard with the wrong spelling — the one the workflow explicitly rejects. Found by a cross-review on #957.

What the page says:

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 form. tag (:447), pypi (:525) and conda (:625) all spell it:

!cancelled() && needs.version_check.result == 'success' &&
(needs.github.result == 'success' || needs.github.result == 'skipped') && ...

The only two occurrences of != 'failure' in the file are comments explaining why it is not used, at :119 and :124-128:

… rather than the sibling files' != 'failure' -- != 'failure' alone still admits cancelled, and a cancelled tag would send conda into its actions/checkout with ref: conda-<version>+0 for a tag tag never pushed, trading a clean skip for a checkout failure.

So the page documents a guard that would reintroduce the defect the real guard was written to avoid. tests/project/test_release_gates.py:624 pins this directly — assertNotIn(f"needs.{dep}.result != 'failure'", condition) — so the behaviour is tested and only the prose disagrees.

The surrounding paragraph is right about everything else, including that cron-vendor.yml, deploy-pages.yml and cron-conda.yml do use != 'failure' for needs.unit-tests.result. The error is confined to the sentence generalising that to the three publishing jobs. Fix is to give the two-state spelling and say why it differs from the sibling files.

Note #953 currently owns releasing.rst and is open with a cross-review verdict, so this wants either its own change after #953 merges, or a deliberate decision to fold it in.

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