Full Release

---
name: full-release
description: Run the full release process end-to-end - prep, tag, CI verification, Homebrew tap, WinGet verification, website sync, and a Discussions announcement
allowed-tools: Bash, Read, Edit, Grep, Glob
---

# Full Release

Orchestrate a complete release: version prep, push + tag, GitHub Actions
verification, Homebrew tap update, WinGet verification, website
documentation sync, and a Discussions announcement. Follows the process
defined in `RELEASING.md` — read it first; this skill sequences it, it
does not replace it.

One gate: explicit user confirmation before pushing the tag (step 5).
Everything before it is local and reversible; everything after it is
published.

## Arguments

`/full-release` — determine version bump automatically from commits
`/full-release 1.2.0` — use the given version instead

## Instructions

### 1. Preflight

Verify before doing anything:

```bash
git branch --show-current          # must be main
git status --porcelain             # must be clean
git fetch origin && git status -sb # must not be behind origin/main
gh auth status                     # gh must be authenticated
ls ../homebrew-tap ../git-flow-next-website  # sibling repos must exist
```

If a sibling repo is missing, continue but note that the corresponding step
will be skipped and must be done manually later.

### 2. Prepare the Release

Follow `.claude/skills/release/SKILL.md` to update CHANGELOG.md and both
version files, verify the build, and create the `chore: Bump version to
X.Y.Z` commit.

If HEAD is already an untagged `chore: Bump version` commit, prep was done
in a prior run — verify its version and changelog are still correct and
reuse it.

### 2a. Sync Contributors

Regenerate the `## Contributors` section of `CONTRIBUTORS.md` from git
history so anyone whose PR merged since the last release is listed. Anyone
with a merged commit qualifies — there is no change-size threshold.

1. Collect every distinct author from commit history:

   ```bash
   git shortlog -sne HEAD | sed -E 's/^ *[0-9]+\t//'
   ```

2. Exclude:
   - Anyone already in `## Project Maintainers` (e.g. Alexander Rinass).
   - AI/bot co-authors — the `Co-authored-by: Claude ...
     <noreply@anthropic.com>` trailers are attribution, not contributors,
     and never go in this list.
3. Collapse duplicate identities (same person, multiple emails) into one
   entry, and resolve each to a GitHub profile link. A
   `<id+handle@users.noreply.github.com>` email encodes the handle directly;
   otherwise resolve via the commit author on GitHub:

   ```bash
   gh api "repos/gittower/git-flow-next/commits/<sha>/pulls" \
     --jq '.[].user.login'
   ```

   If a handle can't be resolved, list the plain name without a link rather
   than guessing.
4. Write the entries alphabetically by name as `- [Name](profile-url)`,
   preserving the explanatory comment at the top of the section. Do not add
   per-contributor descriptions — authorship is the record.

Only touch the `## Contributors` section; leave Maintainers, Original
git-flow Authors, and the rest untouched. If nothing changed, leave the file
as-is. This edit is part of the release prep commit from step 2 (amend it in
if the bump commit is already made).

### 3. Verify Changelog/Tag Coupling

The release workflow extracts the GitHub release notes from CHANGELOG.md by
matching the version header against the tag. Verify the header for this
release is exactly `## [X.Y.Z]` for tag `vX.Y.Z` — a mismatch publishes a
release with an empty body.

Also determine whether this is a preview release (version contains
`-alpha`, `-beta`, or `-rc`). Preview releases skip steps 7–11.

### 4. Confirm with User

**GATE**: Show the user:

- Previous version → new version, and why (which commits drove the bump)
- The new changelog section verbatim
- Whether it is a preview release
- What will happen next (push, tag, CI, Homebrew, WinGet, website)

Wait for explicit confirmation. Do not push anything without it.

### 5. Push and Tag

```bash
git push origin main
git tag vX.Y.Z
git push origin vX.Y.Z
```

### 6. Watch CI and Verify the Release

```bash
gh run list --workflow=release.yml --limit 1   # get the run for the tag
gh run watch <run-id> --exit-status
gh release view vX.Y.Z
```

Verify the release has the platform archives (`.tar.gz`, `.zip`), the
checksums file, and a non-empty body with the changelog content.

If the run fails: stop, report the failure with log excerpts. The tag is
already pushed — after the cause is fixed, the workflow can be re-run from
the same tag (`gh run rerun <run-id>`); do not delete/re-push the tag
unless the fix requires a code change.

### 7. Stamp the Milestone

**Skip for preview releases** — an rc/alpha must not consume the `Next`
name; the milestone is stamped only when a real version ships.

The `Next` milestone accumulates issues/PRs as they merge (via the
`milestone-on-merge` workflow). Now that the version is known and the
release is live, rename `Next` to the actual version, close it, and open a
fresh empty `Next` for the following cycle. Renaming preserves every issue
assignment, so each stamped issue now reads `vX.Y.Z` on its badge.

```bash
NEXT_ID=$(gh api repos/:owner/:repo/milestones --jq '.[]|select(.title=="Next")|.number')
gh api --method PATCH repos/:owner/:repo/milestones/$NEXT_ID -f title="vX.Y.Z" -f state=closed
gh api --method POST  repos/:owner/:repo/milestones -f title="Next"
```

If no open `Next` milestone exists (e.g. it was already stamped in a prior
partial run), just ensure one named `Next` exists for the next cycle and
move on — do not overwrite an already-closed version milestone.

### 8. Update Homebrew Tap

**Skip for preview releases** — `update_formula.rb` picks the newest
non-draft release and does not filter prereleases, so running it after a
preview tag would ship the preview to brew users.

`git-flow-next` is in homebrew-core — `brew install git-flow-next` is the
documented install path, no tap needed — and Homebrew's own `BrewTestBot`
auto-bumps that formula on its own, usually within hours of the tag. This
step is a fallback, not the primary path: it covers the gap before core's
bump lands and stays useful if that automation ever stalls. Don't block
the release on it or treat a failure here as release-breaking.

```bash
cd ../homebrew-tap
git pull
ruby update_formula.rb    # updates formula AND commits itself
git push
```

The script fetches the release checksums and creates the commit — do not
add a manual commit on top. Verify afterwards that
`Formula/git-flow-next.rb` contains the new version.

### 9. Verify the WinGet Submission

**Skipped automatically for preview releases** — the `winget` job is
gated on the tag being stable, so nothing was submitted and there is
nothing to verify.

The release workflow's `winget` job already opened the manifest PR (see
the `WinGet Publishing` section of `RELEASING.md`). Do not submit
anything by hand. Confirm the PR exists:

```bash
gh pr list --repo microsoft/winget-pkgs --state all \
  --search "in:title GitTower.GitFlowNext X.Y.Z"
```

Record the PR URL. One PR covers all three Windows architectures (x86,
x64, arm64). Microsoft's validation bots normally auto-merge within a
few hours — that merge is **not** a release gate, so do not wait for it.

If no PR was opened, inspect the `winget` job in the release run. It is
`continue-on-error`, so it can be marked failed while the run's
conclusion stayed green in step 6 — that is by design, does not mean the
release is broken, and is why `gh run rerun --failed` does not help. Fix
the cause, then look up the job id and re-run that job alone:

```bash
gh run view <run-id> --json jobs --jq \
  '.jobs[] | select(.name == "Submit WinGet manifest") | .databaseId'
gh run rerun --job <job-id>
```

Do not fall back to running komac by hand; the workflow is the only
submission path.

Note: Scoop needs no action — the Main-bucket manifest has
`checkver`/`autoupdate` and Scoop's excavator bot updates it
automatically after each release.

### 10. Sync Website

**Skip for preview releases.**

Work in `../git-flow-next-website` and follow its
`.claude/commands/sync-docs.md`:

- **Every release**: version number in `src/components/Hero.astro`,
  changelog in `src/pages/changelog.astro` (synced from this repo's
  CHANGELOG.md)
- **Only if commands/options/config changed**: `src/content/docs/commands.md`
  and `src/content/docs/configuration.md` from this repo's `docs/` manpages

Verify with `npm run build`. **Leave the changes uncommitted** for user
review — the website deploys automatically when pushed to main, so pushing
is publishing.

### 11. Post a Release Announcement

**Skip for preview releases.**

Post in [GitHub Discussions](https://github.com/gittower/git-flow-next/discussions),
category **Announcements**, for every stable release — even a small
patch release gets a short post; consistency matters more than length.

- Title: `vX.Y.Z released` (reserve a launch-style title like "X.Y.Z is
  here!" for major milestones).
- Body: 1–2 sentences on the headline change, then the notable
  `Added`/`Changed` items from the new CHANGELOG.md section rewritten in
  your own words, not a verbatim dump. Skip internal/doc-only entries.
  Link the GitHub release and the website's changelog page. Follow
  `GITHUB_GUIDELINES.md` for tone (no emoji, no hard-wrapping).
- Check the Ideas and Roadmap discussion categories for anything this
  release closes out (including one already converted to a tracked issue
  via "Closing this in favor of #NNN") and reply there too, linking to
  the announcement.

Find the Announcements category id once per session:

```bash
gh api graphql -f query='{repository(owner:"gittower", name:"git-flow-next"){id discussionCategories(first:20){nodes{id name}}}}'
```

Then post with `createDiscussion` (and `addDiscussionComment` for any
related-discussion reply) via `gh api graphql`.

**GATE**: show the drafted announcement for review before posting — it's
a public post, same bar as any other outward-facing content.

### 12. Report

Summarize:

- Version released, link to the GitHub release
- CI run status
- Homebrew tap: pushed formula version (or skipped + why) — note it's a
  fallback; homebrew-core auto-bump is the primary path
- WinGet: the verified PR URL against `microsoft/winget-pkgs`, or that
  no PR was opened and why (job failed, preview release, etc.)
- Website: files changed, build status, and the remaining manual action —
  review the diff in `../git-flow-next-website`, then commit and push to
  deploy
- Announcement: link to the Discussions post, and any related-discussion
  reply
- Any step that was skipped or failed, stated plainly