goa-release

Goa Release

Use this skill only from the Goa repository. make release pushes branches and tags for Goa, examples, and plugins, so do not run it unless the user explicitly wants to perform the release.

Release Contract

• Goa major version is always 3. Never increment MAJOR; if it is not 3, stop and ask.
• Resolve the target version before making dependency-update commits in any repository. The agent should pick the version from the changes, explain the reasoning, and get confirmation before editing files or running dependency updates.
• Apply semver within v3:
  • Patch release: increment BUILD.
  • Minor release: increment MINOR and reset BUILD=0.
• The preparation commit message must be exactly Prepare v3.x.y, where x is MINOR and y is BUILD.
• Keep the working trees clean between phases. Never discard local changes unless the user explicitly approves it.
• Do not push preparation commits manually. make release-goa runs git pull origin <branch> in examples and plugins; local-ahead preparation commits are fine as long as origin is not ahead. Later, make release-examples and make release-plugins push those preparation commits together with the release commits and tags.

Version Selection

Determine the target version before changing any repository:

1. Read MAJOR, MINOR, and BUILD from the Goa Makefile.
2. Confirm MAJOR=3.
3. Inspect the commits and merged PRs since the previous release tag.
4. Pick the semver bump:
   • Minor when the release includes a user-visible feature, new DSL/runtime capability, or backward-compatible public API addition.
   • Patch when the release only includes fixes, dependency updates, docs, tests, or internal maintenance.
5. Tell the user the selected target version and the specific changes that justify it, then ask for confirmation. If the user supplied an explicit version, validate it against the same reasoning and call out any mismatch before continuing.
6. Use the exact confirmed target version for every preparation commit, tag check, and release command.

Required Repositories

Before release, verify these repositories exist, are on the expected branches, are clean, and are in sync with their upstreams:

• Goa: current repository, expected branch v3.
• Examples: $(go env GOPATH)/src/goa.design/examples, expected branch main.
• Plugins: $(go env GOPATH)/src/goa.design/plugins, expected branch v3.

For each repository:

1. Run git status --porcelain and stop if there are uncommitted changes.
2. Verify the current branch is the expected branch. If not, ask before switching branches.
3. Run git fetch origin.
4. Verify git rev-list --left-right --count @{u}...HEAD reports 0 0. If behind, run git pull --ff-only. If ahead or diverged, stop and ask.
5. Verify the target tag does not already exist locally or on origin.

Preparation Workflow

1. In the Goa repository, run make. Fix failures before continuing.

2. In the Goa repository, run:

   go get -u -v ./...
   go mod tidy
   (cd jsonrpc/integration_tests && go get -u -v ./... && go mod tidy)
   make
   

   The JSON-RPC integration tests are a nested Go module; update and tidy it before rerunning make so integration-test does not fail on stale module metadata. go get should only update go.mod and go.sum. If other files changed in any repository, review why before committing.

3. In the examples repository, run:

   go list -m -f '{{if .Main}}{{.Dir}}{{end}}' all | while IFS= read -r mod; do
     [ -n "$mod" ] && (cd "$mod" && go get -u -v ./... && go mod tidy)
   done
   make
   

   The examples repository has no root go.mod; each example listed in go.work owns its own module. Update and tidy every example module before running make. If files changed, commit them with Prepare v3.x.y. Do not push; make release-examples pushes the branch.

4. In the plugins repository, run:

   go get -u -v ./...
   go mod tidy
   make
   

   If files changed, commit them with Prepare v3.x.y. Do not push; make release-plugins pushes the branch.

5. In the Goa repository, edit only MINOR and BUILD in Makefile for the target version. Leave MAJOR=3.

6. If Goa files changed from dependency updates or the version bump, commit them with Prepare v3.x.y.

7. Re-check all three repositories are clean. They may be ahead of upstream by their preparation commits; that is expected because make release pushes them.

Final Pre-Release Check

make release runs its own clean checks and release preflight, but those checks happen inside a command that can create commits, tags, and pushes. Before running it:

1. In all three repositories, run git fetch origin.
2. Verify git status --porcelain is empty.
3. Verify upstream is not ahead: the first number from git rev-list --left-right --count @{u}...HEAD must be 0. Local-ahead preparation commits are expected.
4. Do not push the local-ahead preparation commits. make release will push them together with the release commits.
5. Reconfirm the target version and that the target tag is absent locally and on origin in all three repositories.

Run And Babysit Release

1. From the Goa repository, run make release.
2. Watch the command until it exits. Track which phase is running: release-goa, release-examples, or release-plugins.
3. If it fails, stop and inspect the failing repository before rerunning anything. Do not blindly rerun the whole release after a tag or push may have succeeded.
4. Before any rerun, inventory local and remote branches and tags for v3.x.y in all three repositories. Never recreate an existing tag, delete a public tag, or force-push unless the user explicitly approves the recovery plan.
5. Fix the root cause, verify the affected repository is in the expected state, then rerun the narrowest safe target or command.
6. When release completes, report the released version and the branch/tag pushes that succeeded.

GitHub Release Notes

After make release succeeds, create GitHub release notes for the Goa tag.

1. Gather the final commit/PR list from the previous Goa tag to the new tag. Include merged PR numbers, titles, authors, and any notable dependency or downstream examples/plugins release work.
2. Identify every human contributor in that range from commit authors and PR authors. Do not miss contributors whose commits were merged by someone else. Exclude bots from the thank-you list unless their work is directly meaningful to users.
3. Write notes that are clear and useful to someone who does not know Goa internals:
   • Start with a short plain-language summary of why the release matters.
   • Use sections only when the amount of change justifies them, such as Highlights, Fixes, Dependencies, Upgrade Notes, and Contributors.
   • Explain user impact before implementation detail. Avoid raw commit-log dumps.
   • Include upgrade notes only for actions users may need to take.
   • Thank every contributor by name or handle.
4. Create or update the GitHub release for v3.x.y with the final notes. Do not mention agent or AI tooling in public release notes.

Announcements

After GitHub release notes are ready, draft announcements for Slack, Bluesky, and Substack. Make them exciting and delightful by showing what the release helps users do, not by adding hype.

Voice rules:

• Lead with the most concrete user payoff.
• Use warm, crisp language with one or two memorable details from the release.
• Avoid empty hype, forced jokes, excessive exclamation marks, launch cliches, and insider-only wording.
• Keep contributor thanks visible and sincere.

Channel guidance:

• Slack: 2-4 short paragraphs or bullets. Sound like a maintainer sharing good news with the community. Lead with the most useful user-facing change, link to the GitHub release, and thank contributors.
• Bluesky: Posts are limited to 300 graphemes. Stay under that limit, include the version, one concrete highlight, and a release link. Make the line feel polished enough to repost.
• Substack: Write a short note for readers who may not know Goa deeply. Use a friendly title, a brief explanation of Goa, a user-centered story for the release highlights, upgrade guidance if any, and contributor thanks. Keep it proportional to the release size.