Prepare Release

5. Determine the version to release

The script's computed next_version is the default, but it can be superseded. Resolve the final version in this priority order, then use it as next_version for every subsequent step. The changelog sections are identical regardless of the version chosen — only the version number changes.

a. Explicit user override (highest priority). If the user requested a specific target version when invoking the skill (e.g. "bump to 1.0.0", "release 0.5.0"), honor it — this overrides both the computed next_version and the pre-1.0 prompt below. Validate it first:

• It must be a valid X.Y.Z version and strictly greater than last_version. If it is equal to or less than last_version, or not a valid version, tell the user and ask for a valid target instead of proceeding.
• Graduating to 1.0.0 is valid even with no breaking change label — it is a deliberate stability commitment. Likewise a version that skips numbers (e.g. 0.3.0 → 0.5.0) is allowed since it was explicitly requested; if the jump looks unintentional, confirm with the user before continuing.

Once validated, use the requested version and skip the rest of this step.

b. Pre-1.0 breaking change. Only when there was no explicit override and the script output includes breaking_change_pre_1_0: true: the release contains a breaking change but the current version is pre-1.0 (0.x.y). By SemVer convention the default is a minor bump (the printed next_version, e.g. 0.4.0), but the user may instead choose to graduate to the major_version_option (1.0.0) to signal a stable public API. Prompt the user to choose:

• Minor bump (default): use the printed next_version (e.g. 0.4.0).
• Major bump: use the major_version_option (1.0.0).

c. Default. Otherwise, use the printed next_version as-is.

6. Create a branch from origin/main

Branch name convention: documentation/changelog-<next_version>

git checkout -b documentation/changelog-<next_version> origin/main

7. Update CHANGELOG.md

Insert a new section above the previous version entry. The version header format is:

## 🚀 [Version <next_version>](https://github.com/fetch-rewards/swift-mocking/releases/tag/<next_version>) - <Month Day, Year> ([Full Changelog](https://github.com/fetch-rewards/swift-mocking/compare/<last_version>...<next_version>))

Paste the sections from the script output (with any entries removed per step 4) beneath it verbatim.

8. Commit and push

git add CHANGELOG.md
git commit -m "Update changelog for Version <next_version>"
git push -u origin documentation/changelog-<next_version>

9. Create the PR

• Title: Update changelog
• Base branch: main
• Label: documentation
• Assignee: graycampbell

Use the repo's PR template at .github/pull_request_template.md. Set the summary to "Updated CHANGELOG.md for Version <next_version>.", check the Documentation checkbox, and check all Checklist items. Write the body to a temp file and pass it via --body-file to avoid multiline escaping issues.

10. Create or update the draft GitHub release notes

Assemble the notes body: the script's section output (no version header line, with any entries removed per step 4), followed by the full-changelog link. The script output already ends with a blank line, so append the link directly. The assembled body looks like:

### ✨ Features

- Example entry ([#NNN](https://github.com/fetch-rewards/swift-mocking/pull/NNN))

[Full Changelog](https://github.com/fetch-rewards/swift-mocking/compare/<last_version>...<next_version>)

Write the assembled body to a temp file, then check whether a release already exists for <next_version>:

gh release list --repo fetch-rewards/swift-mocking

• Listed as Draft: update it:

  gh release edit <next_version> --repo fetch-rewards/swift-mocking --notes-file <path>

• Listed but not a draft (already published): warn the user — do not overwrite a published release.
• Not listed: create a draft:

  gh release create <next_version> --repo fetch-rewards/swift-mocking --draft --title "Version <next_version>" --notes-file <path>