Skip to content

docs: unprefixed release tags run nothing rather than failing fast - #74

Merged
dmccoystephenson merged 2 commits into
mainfrom
docs/unprefixed-release-tags
Nov 15, 2026
Merged

dmccoystephenson merged 2 commits into
mainfrom
docs/unprefixed-release-tags

Conversation

@dmccoystephenson

Copy link
Copy Markdown
Member

Summary

Stage A documentation accuracy sweep. Two claims were found to disagree with the repository's actual release state:

  • RELEASING.md stated that a tag not equal to v + __version__ makes "the build fail fast before anything is published". That holds only for a v-prefixed tag with a mismatched version. A tag without the prefix matches no publish.yml trigger (v*.*.*), so the workflow never runs and nothing is reported. The remote tags 0.2.0 and 0.3.0.dev20260808 are unprefixed, and gh run list --workflow publish.yml returns zero runs. The paragraph now describes both failure modes and links release: version tags are pushed without the 'v' prefix publish.yml requires, so no release has ever been published #34.
  • README.md said pip install graphik "will not resolve until the first release is tagged". Release tags already exist, but nothing has been published, so the wording now says "published".

No code, workflow or version file is changed. #34 stays open: the choice between fixing the tagging practice and broadening the trigger is still a maintainer decision. This PR only stops the docs from contradicting that issue.

Issues skipped this cycle

Every open issue is waiting on a maintainer decision or touches a path excluded from autonomous change:

Test plan

  • Docs claims checked against .github/workflows/publish.yml (trigger v*.*.*), git ls-remote --tags origin, and gh run list --workflow publish.yml (no runs)
  • Local pytest: not run, because the dispatch sandbox denied the command. Recorded as UNVERIFIED-not-applicable since only Markdown files change. CI (test.yml) runs on this PR.

No tracking issue: the drift was found during the triage sweep. The PR references #34 but does not close it.

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 14, 2026 20:04
RELEASING.md said a tag not equal to v + __version__ fails the build
fast. That only holds for a v-prefixed tag; an unprefixed one matches no
publish.yml trigger and runs nothing, which is how 0.2.0 and
0.3.0.dev20260808 went unpublished (#34). README's Installation note also
tied PyPI availability to a release being tagged, though tags exist and
none was published.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The workflow never running is observable; whether PyPI's one-time setup
would also have blocked a publish is not, so drop the causal claim.

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

Copy link
Copy Markdown
Member Author

Self-review rubric (head 7ace2f9):

  • Scope: PASS — only README.md (1 line) and RELEASING.md (1 paragraph) are changed, and both changes fix the documented drift.
  • Tests-new: PASS (n/a) — no public method was added or changed.
  • Tests-fix: PASS (n/a) — this is a docs-only change with no bug fix.
  • Sibling structure: PASS — no new files.
  • Sibling renames: PASS (n/a) — nothing renamed.
  • Docs: PASS — the claims were re-checked against publish.yml (trigger v*.*.*, tag/version step strips v), git ls-remote --tags origin (0.2.0, 0.3.0.dev20260808, v0.1), and gh run list --workflow publish.yml (no runs).
  • Issue resolution: PASS — release: version tags are pushed without the 'v' prefix publish.yml requires, so no release has ever been published #34 is referenced but not closed. Its decision is still open.
  • Manual validation: PASS via CI — Compile and test passed on 3.9–3.13 for this head. Local pytest was denied by the dispatch sandbox, so it is recorded as UNVERIFIED-not-applicable (Markdown only).
  • camelCase / Backward-compat / Headless / No new deps: PASS (n/a) — graphik.py and the tests are unchanged.
  • Version sync: PASS (n/a) — _version.py is untouched.

One finding, now fixed: the first revision said the unprefixed tags were "why no release has been published". That overstated the cause, because PyPI's one-time Trusted Publisher setup could also be missing and cannot be checked from the repository. Commit 7ace2f9 narrows the claim to the observable fact that the publish workflow has never run.

Out-of-diff note: the step-3 example in RELEASING.md (git tag v0.2.0) uses a version that already exists as the unprefixed tag 0.2.0. It is illustrative ("e.g.") and was left unchanged.

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


drafted by Claude on behalf of Daniel Stephenson

@dmccoystephenson
dmccoystephenson merged commit 2467b01 into main Nov 15, 2026
5 checks passed
@dmccoystephenson
dmccoystephenson deleted the docs/unprefixed-release-tags branch November 15, 2026 03:06
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