docs: update release process for immutable releases with tag-first workflow

[erraggy]

Summary

Updates release documentation to implement a tag-first workflow compatible with GitHub's immutable releases feature.

Changes

CLAUDE.md

• Updated "Creating a New Release" section with tag-first workflow
• Step 5 now instructs users to ask Claude Code to generate release notes
• Added troubleshooting for tag-first workflow failures

RELEASES.md

• Complete rewrite (602 lines → 392 lines)
• Removed outdated draft-first approach documentation
• Streamlined 8-step process with tag-first workflow
• Updated configuration reference with actual YAML

planning/releases-with-immutability.md

• New planning document with detailed analysis
• Research findings from GitHub and GoReleaser docs
• Explanation of why tag-first works vs previous approaches
• Implementation checklist (all items verified complete)

Why Tag-First Works

The Problem: With immutable releases enabled, previous approaches failed because:

1. Creating published release first → immediately immutable → 422 errors when uploading assets
2. Creating draft via gh release create --draft → doesn't push tag → workflow doesn't trigger until published → release immutable when workflow runs → 422 errors

The Solution: Tag-first workflow:

1. Push tag first → triggers workflow immediately
2. Workflow creates draft release (mutable)
3. Workflow uploads assets to draft (still mutable)
4. Human reviews and publishes when ready
5. Immutability only applies after publish

Testing Plan

After merge, we'll test with v1.10.0-rc1 to verify the workflow before creating the actual v1.10.0 release.

Related

• Closes Homebrew release workflow fails with release immutability enabled #39
• See also: planning/release-issues.md for historical context

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 55.31%. Comparing base (3ed8a8f) to head (23655fd).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #40      +/-   ##
==========================================
+ Coverage   53.00%   55.31%   +2.30%     
==========================================
  Files          31       30       -1     
  Lines        8363     6472    -1891     
==========================================
- Hits         4433     3580     -853     
+ Misses       3203     2222     -981     
+ Partials      727      670      -57     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[claude]

PR Review: Release Process Documentation Update

Summary

This PR updates the release documentation to implement a tag-first workflow compatible with GitHub's immutable releases feature. The changes are well-motivated and address a real pain point (#39). Overall, this is a solid documentation improvement with good technical accuracy.

Strengths ✅

1. Clear Problem Definition: The PR clearly explains why the tag-first approach works where previous methods failed
2. Comprehensive Documentation: Three files work together well:
   • CLAUDE.md: Concise operational guidance for Claude Code
   • RELEASES.md: Detailed step-by-step workflow for humans
   • planning/releases-with-immutability.md: Technical analysis and rationale
3. Security Benefits: Properly documents the security advantages of immutable releases
4. Good Troubleshooting Section: Covers common failure scenarios with recovery steps
5. Verified Configuration: The checklist in the planning doc shows all prerequisites are already in place

Issues Found 🔍

1. Step Numbering Inconsistency (Minor)

The three files have different step sequences:

• CLAUDE.md: 7 steps (includes "Generate and set release notes" as Step 5)
• RELEASES.md: 8 steps (includes "Determine Version Number" as Step 2, "Generate and Set Release Notes" as Step 6)
• planning/releases-with-immutability.md: 7 steps ("Edit Release Notes" as Step 5)

Recommendation: Standardize the step numbering across all three documents. The RELEASES.md version with 8 steps seems most complete and should be the canonical reference.

2. Cross-Reference Path Inconsistency (Minor)

In RELEASES.md line 387:

- [planning/release-issues.md](./planning/release-issues.md)

In CLAUDE.md line 286:

See [planning/releases-with-immutability.md](planning/releases-with-immutability.md)

Recommendation: Use consistent relative paths - either with ./ prefix or without. I'd suggest without for cleanliness.

3. Step 5 Title Mismatch Between CLAUDE.md and RELEASES.md (Minor)

• CLAUDE.md Step 5: "Generate and set release notes" (emphasizes Claude Code automation)
• RELEASES.md Step 6: "Generate and Set Release Notes" (same concept, different numbering)

These describe the same action but are numbered differently.

Code Quality Assessment

Since this is a documentation-only PR, traditional code quality metrics don't apply, but documentation quality is excellent:

• ✅ Clarity: Instructions are clear and actionable
• ✅ Completeness: All steps are covered with command examples
• ✅ Accuracy: Technical details are correct (verified against GitHub docs)
• ✅ Consistency: Mostly consistent formatting and style
• ✅ Maintainability: Well-structured with clear sections

Performance Considerations

N/A - Documentation only

Security Concerns

✅ None identified. In fact, this PR improves security posture by:

• Enabling and documenting immutable releases
• Preventing tag/asset tampering after publication
• Maintaining PAT security best practices

Test Coverage

N/A - Documentation only. However, the planning doc includes a helpful implementation checklist showing all items are verified complete.

Recommendations

1. Before Merge: Standardize step numbering across all three files to match RELEASES.md (8 steps)
2. Before Merge: Standardize cross-reference link syntax (remove ./ prefix for consistency)
3. Consider: Adding a version/date stamp to RELEASES.md to track when the workflow was last updated
4. Consider: Testing the workflow with a release candidate (v1.10.0-rc1) as mentioned in the PR description

Breaking Changes

None - This is documentation only.

Verdict

Approve with minor fixes recommended ✅

The core content is excellent and solves a real problem. The inconsistencies are minor presentation issues that should be addressed but don't block merging. Once step numbering is standardized, this will be a high-quality documentation update.

---

Reviewed by: Claude Code (Sonnet 4.5)
Review Date: 2025-11-26