Make publish.yml github-release job idempotent

[cmeans-claude-dev]

Summary

Fixes #12 with Option C: the github-release job in publish.yml is now idempotent AND reads its Release body from CHANGELOG.md instead of using auto-generated notes.

Problem recap

During the v0.5.0 publish (run 24263840766):

Job	Status
build (tests + wheel)	✅ SUCCESS
publish-pypi (PyPI upload)	✅ SUCCESS — v0.5.0 live
github-release	❌ FAILED — HTTP 422: Release.tag_name already exists

The workflow tried to gh release create a Release that was already created manually (with hand-written notes), and failed with 422. This marked the whole workflow as failed even though everything important (PyPI) succeeded.

The root cause was two-fold:

1. The step wasn't idempotent. gh release create fails on existing tags.
2. --generate-notes produces low-quality output, which incentivized pre-creating releases manually — which triggered Rename package to mcp-synology, add transfer module and icons #1.

Fix (Option C from the issue)

Both problems addressed together so neither recurs.

1. Extract release body from CHANGELOG.md

A small awk block extracts the section between the current version's ## <version> heading and the next ## heading:

VERSION="${TAG#v}"
awk -v version="$VERSION" '
  $0 ~ "^## "version"( |\\()" {flag=1; next}
  flag && /^## / {exit}
  flag
' CHANGELOG.md > release_notes.md
sed -i '/./,$!d' release_notes.md   # strip leading blank lines

The heading itself is skipped (the Release title already says v0.5.0, no need to duplicate). If extraction produces an empty file (e.g. emergency tag without CHANGELOG prep), the step falls back to --generate-notes with a ::warning:: annotation so the workflow UI makes it visible.

2. Idempotent create-or-update

if gh release view "$TAG" >/dev/null 2>&1; then
  gh release edit "$TAG" --title "$TAG" --notes-file release_notes.md
else
  gh release create "$TAG" --title "$TAG" --notes-file release_notes.md
fi

Works whether a Release was pre-created or not. Content flows from CHANGELOG.md either way.

Verification

Tested the shell logic locally against the current CHANGELOG.md:

• v0.5.0 extraction → 34 lines of content starting with ### Changed, ending cleanly at the next ## header. First line is ### Changed (not the version heading), confirming the title-duplication avoidance works.
• Nonexistent version extraction → empty file, use_changelog=false, falls back to --generate-notes. No crash.
• YAML validity → python3 -c 'import yaml; yaml.safe_load(...)' passes.

Full end-to-end testing requires a real tag push, so the first real exercise of both the create and edit paths will be the next release. Failure mode is loud (workflow red), and the PyPI publish step is independent and already succeeded before this job runs, so there's zero risk to actual package distribution.

Why environment variables instead of ${{ }} in run:

Both shell blocks use env: to pass TAG/USE_CHANGELOG instead of interpolating ${{ github.ref_name }} directly into the script. GitHub's docs recommend this for scripts because it avoids shell-injection surface if a tag name ever contains shell metacharacters. Standard practice, not specific to this fix.

Files changed

• .github/workflows/publish.yml — github-release job rewritten (51 insertions, 4 deletions)

Test plan

• CI green — this only touches the publish workflow, so normal CI (ci.yml) should pass unchanged
• YAML lint passes
• Next release (v0.5.1 or v0.6.0) exercises the create path and confirms CHANGELOG-derived notes appear on the Release page
• Manually re-running the workflow against an existing v0.5.0 tag would exercise the edit path without cutting a new version, if we want to verify sooner

Closes #12

🤖 Generated with Claude Code

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cmeans]

Adding QA Active — beginning review. This is a CI workflow PR so verification will focus on: YAML validity, the awk extraction logic against the real CHANGELOG.md, the gh release create/edit idempotency paths, the env var injection-safety pattern, and the empty-file fallback to --generate-notes.

[cmeans]

QA Review — Round 1

Verdict: Ready for QA Signoff. Clean review — no substantive findings, three minor observations on the regex/convention dependencies that are dormant in practice.

Verification (fresh in this session, commit ca8bed5)

The interesting parts of this PR are testable in isolation, so I exercised them locally rather than waiting for the next real release.

Normal CI sanity (workflow change should not affect source-code CI):

• uv run pytest: 312 passed, 94 deselected, 7 warnings in 16.66s
• uv run ruff check .: All checks passed!
• uv run mypy src/: Success: no issues found in 27 source files

YAML validity:

• python3 -c "import yaml; yaml.safe_load(open('.github/workflows/publish.yml'))" → no error

awk extraction against the real CHANGELOG.md (the bit the PR description claims I should be able to verify locally):

For VERSION=0.5.0:

• Output: 34 lines, 3594 bytes
• First line: ### Changed (the ## 0.5.0 heading itself is correctly excluded by the next after the flag is set — confirms title-duplication avoidance works)
• Last lines: the ### Fixed block ending at the ## 0.4.1 boundary — clean cut, no bleed-through into the previous version's section
• Line count and starting heading both match what the PR description claims

For a nonexistent VERSION=9.9.9:

• Output: 0 bytes
• [ -s release_notes.md ] evaluates false → use_changelog=false is set → workflow falls through to gh release create/edit ... --generate-notes (or --title only on the edit branch)
• Fallback path works as designed

Code review

Idempotency logic at lines 99-114 is the right shape: gh release view "$TAG" >/dev/null 2>&1 is the canonical existence check, then branch into edit-vs-create. The four-way matrix (exists × CHANGELOG-or-not) is handled distinctly:

• exists + CHANGELOG → gh release edit $TAG --title $TAG --notes-file …
• exists + no CHANGELOG → gh release edit $TAG --title $TAG (preserves whatever notes are there; the comment at line 104 calls out that you can't regenerate auto-notes on edit)
• new + CHANGELOG → gh release create $TAG --title $TAG --notes-file …
• new + no CHANGELOG → gh release create $TAG --title $TAG --generate-notes

That's the correct decomposition.

Injection safety is correctly handled via env: blocks at lines 63-64 and 91-94 rather than ${{ … }} interpolation into the shell script. This matches the GitHub docs guidance the PR description cites — standard practice, but worth confirming it's actually applied at every interpolation point. It is.

sed -i '/./,$!d' release_notes.md at line 80 is the standard "strip leading blank lines" idiom. GNU sed (Ubuntu runners), so the bare -i works.

Observations (non-blocking)

1. $VERSION is inserted into the awk regex without escaping. Line 73:

$0 ~ "^## "version"( |\\()"

The . characters in 0.5.0 are regex metacharacters (match any single char), so a CHANGELOG line ## 0X5X0 (date) would technically match for VERSION=0.5.0. Dormant in practice — version numbers are always literal dots and CHANGELOG entries are always literal dots, so dots match dots. But a future version scheme with pre-release suffixes (e.g., 0.5.1-rc1) or a typo in the CHANGELOG could surface latent issues. A gsub(/\./, "\\.", version) inside awk, or pre-escaping in shell, would close the loophole. Not a blocker.

2. The regex requires a space or ( after the version. ( |\() in the awk pattern means a future CHANGELOG entry written as just ## 0.6.0 (no date suffix, no trailing space) would not match. This relies on the existing convention ## X.Y.Z (date). Worth a one-line comment in the workflow noting the convention dependency, so a future contributor doesn't accidentally break extraction by changing CHANGELOG style. Not a blocker.

3. Substring-match edge case — verified safe. For VERSION=0.5.1 against a hypothetical ## 0.5.10 (date) line: after matching 0.5.1, the next character would need to be space or (, but ## 0.5.10 has 0 there, so the regex correctly doesn't match. Mentioning this as a positive — the ( |\() anchor specifically prevents this category of bug.

Untestable in this PR cycle (acknowledged)

End-to-end testing of the actual gh release create/edit paths against the real GitHub API requires a real tag push. The PR description acknowledges this. Mitigations are in place:

• The PyPI publish step (the actually-important one for users) is independent and runs first, so a github-release failure on the next release would still leave PyPI in a correct state — same as the v0.5.0 incident.
• The shell logic for extraction and fallback is fully exercised by my local tests above, so the only thing the next real release will be exercising for the first time is the gh release API surface itself.

Test plan checkboxes (verifiable items only)

• CI green — confirmed: lint, typecheck, test 3.11/3.12/3.13, qa-approved, on-push all SUCCESS
• YAML lint passes — yaml.safe_load clean
• Next release exercises the create path — out of QA scope, owner-verified post-merge
• Manual workflow re-run against existing v0.5.0 tag exercises the edit path — out of QA scope, optional owner verification

Summary

Targeted CI fix, well-scoped (one file, one job rewrite). The Option C choice — fix idempotency AND switch to CHANGELOG-derived notes — is the right call: it removes both the technical footgun (existing-tag 422) and the incentive to pre-create releases manually that triggered the original failure. Local verification of the awk logic, YAML validity, and the fallback path all pass. No substantive findings.

Applying Ready for QA Signoff as the final act. Awaiting maintainer for QA Approved + merge.

[cmeans]

QA audit — Round 1 complete (clean)

CI workflow PR. Verification focused on testable parts of the change rather than waiting for the next real tag push.

Verification (fresh in this session, commit ca8bed5):

• pytest sanity: 312 passed, 94 deselected (workflow change doesn't affect normal CI ✓)
• ruff check: All checks passed!
• mypy src/: no issues found in 27 source files
• YAML validity: yaml.safe_load clean
• awk extraction for v0.5.0: 34 lines, 3594 bytes, first line ### Changed, ends at ## 0.4.1 boundary cleanly — matches PR body claim exactly
• Empty fallback path: nonexistent version produces 0-byte file, [ -s ] correctly false, would trigger use_changelog=false → --generate-notes
• All CI checks SUCCESS (lint, typecheck, test 3.11/3.12/3.13)

No substantive findings. Three minor observations on regex/convention dependencies (unescaped $VERSION dots, requirement for space-or-( after version, positive note about substring-match edge case being correctly handled) — all non-blocking and dormant in practice.

Applying Ready for QA Signoff as the final act. Awaiting maintainer for QA Approved + merge.

[cmeans]

LGTM