Skip to content

docs(releasing): document that publish.yml only fires on three-part v tags - #76

Merged
dmccoystephenson merged 2 commits into
mainfrom
docs/releasing-three-part-tag-filter
Nov 18, 2026
Merged

dmccoystephenson merged 2 commits into
mainfrom
docs/releasing-three-part-tag-filter

Conversation

@dmccoystephenson

Copy link
Copy Markdown
Member

Summary

  • RELEASING.md said that a v-prefixed tag whose version does not match __version__ "fails the build before anything is published". That only holds for tags the publish.yml trigger matches. The trigger is the glob v*.*.*, which needs two dots after the v, so a tag such as v1.0 never starts the workflow at all. That is true even when the tag equals v + __version__, so following the documented rule exactly with a two-part version produces a silent no-op instead of a release.
  • The paragraph now states the three-part requirement and groups both silent cases (no v prefix; fewer than three parts) together. It also notes that the existing v0.1 tag on the remote has that shape. No claim is made about whether v0.1 was ever meant to publish: it may predate the workflow.
  • Documentation only. publish.yml is not touched, since workflow files are excluded from autonomous change. Whether the trigger should be broadened is left to the maintainer decision already pending in release: version tags are pushed without the 'v' prefix publish.yml requires, so no release has ever been published #34.

No tracking issue: the gap was found during a Stage A documentation accuracy sweep.

Evidence

  • publish.yml line 10: - "v*.*.*".
  • git ls-remote --tags origin → 0.2.0, 0.3.0.dev20260808, v0.1.
  • gh run list --workflow publish.yml → no runs.
  • Glob check (fnmatch, which has the same *-matches-dots semantics as GitHub's tag filter for slash-free names): v0.1 False, v1.0 False, v0.2.0 True, v0.3.0.dev20260808 True, 0.2.0 False.

Test plan

  • python3 -m pytest -q src/test/python: 157 passed (headless, via conftest.py's dummy SDL drivers). No code or test changed. The run only shows that the tree is unaffected.
  • The new wording checked against publish.yml's trigger and the remote tag list above.

Skipped issues

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

🤖 Generated with Claude Code


drafted by Claude on behalf of Daniel Stephenson

dmccoystephenson and others added 2 commits November 17, 2026 21:09
The v*.*.* trigger needs two dots after the v, so a tag such as v1.0
never starts the workflow even when it equals v + __version__. The doc
claimed every mismatched v-prefixed tag fails the build loudly.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dmccoystephenson

Copy link
Copy Markdown
Member Author

Self-review rubric (scored against the diff and command output):

  • Scope: PASS. Only RELEASING.md changed, in the one paragraph about tag rules.
  • Tests-new: PASS (not applicable). No public method was added.
  • Tests-fix: PASS (not applicable). No bug fix to code. Documentation only.
  • Sibling structure: PASS. No new file. The paragraph keeps the file's 80-column wrapping.
  • Sibling renames: PASS (not applicable). Nothing was renamed.
  • Docs: PASS. Line 6 (vX.Y.Z) already matches the new wording. README.md does not describe tag rules, so it needs no change.
  • Issue resolution: PASS (not applicable). No Closes. The PR body notes that the gap has no tracking issue.
  • Manual validation: PASS. All five checks Compile and test (3.9–3.13) are green on the PR head. Locally, python3 -m pytest -q src/test/python ran 157 tests and all passed.
  • camelCase / Backward-compat / Headless / No new deps: PASS (not applicable). No Python changed.
  • Version sync: PASS (not applicable). _version.py was not touched.

Finding fixed during review:

  • RELEASING.md:58: the old sentence "The 0.2.0 and 0.3.0.dev20260808 tags were pushed that way" came right after the new v0.1 parenthetical, so "that way" could be read as "with too few parts". It now says "pushed without the prefix". This was fixed in the second commit.

Judgment call, raised for a maintainer and not changed:

This review was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).


drafted by Claude on behalf of Daniel Stephenson

@dmccoystephenson
dmccoystephenson merged commit 61c6432 into main Nov 18, 2026
5 checks passed
@dmccoystephenson
dmccoystephenson deleted the docs/releasing-three-part-tag-filter branch November 18, 2026 04:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant