fix(goreleaser): change release mode to replace for automated releases

[erraggy]

Summary

Fixes the GoReleaser configuration to prevent the "Cannot upload assets to an immutable release" error that occurred during the v1.9.5 release attempt.

Problem

When creating a release using gh release create first, GitHub marks the release as immutable. GoReleaser then fails to upload assets with error 422.

Solution

Changed .goreleaser.yaml release configuration from keep-existing to replace mode, allowing GoReleaser to fully manage the release creation and asset uploads.

Changes

• release.mode: keep-existing → replace
• release.replace_existing_draft: false → true
• Updated comments to reflect the new workflow

Testing

After merging, the v1.9.6 release can be created by simply using gh release create v1.9.6 and letting GoReleaser handle everything.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 36.81%. Comparing base (17e636e) to head (606f34f).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #30   +/-   ##
=======================================
  Coverage   36.81%   36.81%           
=======================================
  Files          30       30           
  Lines        7361     7361           
=======================================
  Hits         2710     2710           
  Misses       4088     4088           
  Partials      563      563           

☔ 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]

Code Review for PR #30

Summary

This PR addresses a critical issue with the GoReleaser workflow where gh release create marks releases as immutable, preventing GoReleaser from uploading assets. The fix changes the release mode from keep-existing to replace.

---

✅ Strengths

1. Correctly identifies the problem: The PR accurately diagnoses the issue - GitHub marks releases as immutable when created via gh release create, causing GoReleaser to fail with HTTP 422 errors.

2. Clean, focused change: The modification is minimal and surgical, changing only the necessary configuration options.

3. Good documentation: Comments in the YAML file are updated to reflect the new workflow.

4. Follows conventional commits: The commit message format is correct (fix(goreleaser):).

---

⚠️ Critical Issues

1. Conflicts with CLAUDE.md Documentation

The change directly contradicts the documented release workflow in CLAUDE.md:604-605:

1. Create a GitHub Release with detailed notes using `gh release create`
2. GoReleaser automatically triggers, adds binaries to your release, and publishes to Homebrew

And in CLAUDE.md:702:

This workflow creates the GitHub Release first with detailed notes, then GoReleaser adds binaries and publishes to Homebrew.

Impact: With mode: replace, if you follow the documented workflow of creating the release first with detailed notes, GoReleaser will completely replace that release, potentially overwriting your carefully crafted release notes.

2. Comment vs. Behavior Mismatch

Line 76 says: # Create as draft first, then publish after verification

But draft: false (line 77) means it will NOT create a draft - it will publish immediately. This is misleading.

3. Loss of Manual Release Note Control

The original workflow's main benefit was maintaining full control over release notes. With mode: replace, you lose this control because GoReleaser will generate the changelog automatically from commits.

---

📋 Recommendations

Option A: Update CLAUDE.md to Match New Workflow (Simpler)

If you want to keep mode: replace, you should:

1. Update CLAUDE.md to remove references to creating releases first with gh release create
2. Change the workflow to let GoReleaser handle everything:
   • Tag the commit: git tag v1.9.6
   • Push the tag: git push origin v1.9.6
   • Let GoReleaser create the release and auto-generate changelog
3. Fix the comment on line 76 to be accurate:

   # GoReleaser creates and manages the release
   draft: false
   # Or set to true if you want to review before publishing

Option B: Fix the Real Issue While Preserving Manual Control (Recommended)

Keep the original workflow but fix the immutability issue:

release:
  # Don't try to create the release - it's already created by gh release create
  mode: append
  # Keep the release notes as-is
  draft: false
  # Don't modify the existing release
  replace_existing_draft: false

Wait - actually, checking GoReleaser docs, mode: append doesn't exist. The available modes are:

• replace: Replace existing release
• keep-existing: Keep existing release (fails if release exists)
• draft: Always create as draft

The real issue is that keep-existing fails when the release already exists. However, the documented workflow of creating the release first is incompatible with GoReleaser's design.

Option C: Hybrid Approach - Use Draft Mode

release:
  mode: replace
  # Create as draft so you can review and edit notes before publishing
  draft: true
  replace_existing_draft: true

Then after GoReleaser runs:

1. Review the draft release on GitHub
2. Edit the auto-generated notes to add your detailed context
3. Publish manually

---

🔍 Testing Concerns

The PR states: "After merging, the v1.9.6 release can be created by simply using gh release create v1.9.6"

This is incorrect with the current changes. With mode: replace, you should NOT use gh release create first. Instead:

• Tag and push: git tag v1.9.6 && git push origin v1.9.6
• Let GoReleaser create the release

If you use gh release create first with these settings, GoReleaser will replace your release notes.

---

🎯 Recommended Changes Before Merging

1. Update CLAUDE.md to document the actual workflow that works with mode: replace
2. Fix the comment on line 76 to accurately describe draft: false
3. Update the PR description to correct the testing instructions
4. Consider using draft: true to preserve the ability to review and edit release notes before publishing

---

📊 Code Quality Assessment

• Syntax: ✅ Valid YAML
• Security: ✅ No security concerns
• Performance: ✅ N/A for config file
• Best Practices: ⚠️ Needs alignment with documented workflow
• Test Coverage: ⚠️ Configuration change, but workflow documentation needs testing

---

💡 Alternative Solution

Consider investigating whether the GitHub Actions workflow could be modified to:

1. Use GoReleaser to create a draft release
2. Use a subsequent step to update the release notes
3. Publish the release

This would preserve automated builds while allowing custom release notes.

---

Final Verdict

Conditional Approval - The code change itself is valid, but the PR needs:

1. Documentation updates to CLAUDE.md
2. Accurate comment on line 76
3. Corrected testing instructions

Without these changes, this PR will create confusion between the documented workflow and the actual behavior.