fix(goreleaser): create releases as drafts to allow asset uploads

[erraggy]

Summary

Fixes the persistent "Cannot upload assets to an immutable release" error by creating releases as drafts.

Problem

Even with mode: replace, GoReleaser creates releases that become immutable before assets can be uploaded, causing 422 errors.

Solution

Set draft: true in .goreleaser.yaml so releases are created as drafts, allowing asset uploads to succeed.

Workflow

1. Push tag triggers GoReleaser
2. GoReleaser creates DRAFT release with all assets
3. Manually publish release when ready

🤖 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 (cc4c2d9).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #31   +/-   ##
=======================================
  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 #31

Summary

This PR addresses the "Cannot upload assets to an immutable release" error by simplifying the GoReleaser release configuration to use draft releases.

Changes Analysis

Modified File: .goreleaser.yaml

Before:

release:
  mode: replace
  draft: false
  replace_existing_draft: true

After:

release:
  draft: true

---

✅ Strengths

1. Simplification: The change removes complexity by dropping mode: replace and replace_existing_draft settings that were causing conflicts.

2. Root Cause Fix: Creating releases as drafts prevents the immutability issue - drafts remain mutable until manually published, allowing GoReleaser to upload all assets successfully.

3. Clean Approach: Rather than fighting with mode: replace, this leverages the natural draft→publish workflow that GitHub supports.

4. Documentation: The comment clearly explains the purpose: "Create as draft to allow asset uploads before publishing"

---

🔍 Considerations & Recommendations

1. Documentation Update Required ⚠️

The CLAUDE.md file currently documents a workflow where gh release create is used to create the release first, then GoReleaser adds binaries (lines 700-758). With this change, the workflow is now:

1. Push tag → GoReleaser creates DRAFT release with assets
2. Manually publish the draft release

Recommendation: Update CLAUDE.md section "Release Process (Recommended Workflow)" to reflect this new approach:

**Release Process (Recommended Workflow):**

This workflow uses GoReleaser to create draft releases with all assets, then manually publishes when ready.

1. **Determine the version number** based on the changes included (see SemVer rules above)

2. **Test the release configuration locally** (optional but recommended):
   ```bash
   make release-test

3. Push the version tag to trigger GoReleaser:

   git tag v1.7.1
   git push origin v1.7.1

4. Monitor the automated build:
   The GitHub Actions workflow will automatically:

   • Create a DRAFT release
   • Build binaries for all platforms (Linux, macOS, Windows)
   • Upload binary archives to the draft release
   • Publish the Homebrew formula to homebrew-oastools

5. Edit and publish the release:

   • Go to https://github.com/erraggy/oastools/releases
   • Find the draft release
   • Edit the release notes with detailed changelog
   • Click "Publish release" when ready

#### 2. **Release Notes Entry Point** 📝

With draft releases, you lose the ability to pre-write detailed release notes via `gh release create`. The workflow now requires:
- Tag push → Draft created with auto-generated notes
- Manual editing in GitHub UI to add proper release notes

**Consider:** You might want to prepare release notes in a local file first, then copy/paste into the GitHub UI when publishing the draft.

#### 3. **Automation Opportunity** 🤖

If you want to combine the best of both approaches (pre-written notes + draft safety), you could:

**Option A:** Use `gh release create` with `--draft` flag:
```bash
gh release create v1.7.1 --draft \
  --title "v1.7.1 - Description" \
  --notes "Detailed notes here"

Then let GoReleaser add assets to the existing draft.

Option B: Keep the current approach and document a notes template that can be copy/pasted.

4. Homebrew Publishing Timing 🍺

Question: Does the Homebrew formula get published when the draft is created, or when it's published?

• If published on draft creation: Users can brew install before release notes are finalized
• If published on release publish: Better alignment with public announcement

Recommendation: Test this behavior and document it in CLAUDE.md troubleshooting section.

---

🎯 Code Quality Assessment

• Correctness: ✅ The change is syntactically correct and follows GoReleaser v2 schema
• Best Practices: ✅ Using drafts is a recommended pattern for release automation
• Security: ✅ No security implications
• Performance: ✅ No performance impact
• Testing: ⚠️ Should verify with an actual release that draft workflow works end-to-end

---

🧪 Testing Recommendations

1. Local Test: Run make release-test to verify snapshot builds still work
2. Integration Test: Create a test tag (e.g., v1.0.0-test) to verify:
   • Draft release is created
   • Assets upload successfully
   • Homebrew formula updates correctly
   • Manual publish works as expected
3. Rollback Plan: Document how to handle failed releases (delete draft, delete tag, retry)

---

📋 Action Items

• Update CLAUDE.md release process documentation
• Add release notes template/example to CLAUDE.md
• Document Homebrew publishing timing behavior
• Add troubleshooting entry for draft release workflow
• Consider adding a release checklist to CLAUDE.md that includes "Publish draft release"

---

✅ Approval Recommendation

APPROVED with documentation updates recommended.

The code change itself is sound and solves the immediate problem. The main action item is updating documentation to match the new workflow. This can be done in a follow-up PR if needed.

---

Great work fixing this persistent issue! The draft approach is cleaner than fighting with mode: replace.