--- name: release description: Prepare and publish a submarine release. Finds the latest release, picks the next semver from the changes since, runs a release check, creates and pushes the git tag, writes the release notes, hands over to the developer for `make release`, then verifies the GitHub release. Use only when the user asks to release. disable-model-invocation: true --- # Release submarine A release is built on the developer's machine (`make release`, see `docs/architecture.md#distribution`). `make release` creates the GitHub release of the **clean `vX.Y.Z` tag at HEAD**, with the binaries as assets. This skill does everything around it. The developer runs `make release` themselves, in the middle: you never run it and never read or print `.env`, `GH_TOKEN` or `GITEA_TOKEN`. Pushing a tag and creating a release are outward-facing and hard to undo. Do them only after the confirmation in step 5, and never force-push, move or delete a tag without asking. GitHub: owner `simonfranken`, repo `submarine`, remote `origin`. ## 1. Preconditions Stop and tell the user, if any of these fails: ```sh git fetch origin --tags git branch --show-current # main git status --porcelain # empty: make release refuses a dirty tree git rev-parse HEAD origin/main # equal: HEAD is pushed, nothing to release from a local-only commit git tag --points-at HEAD # empty: HEAD is not released yet gh auth status >/dev/null 2>&1 || grep -q '^GH_TOKEN=.\+' .env # one holds: only test, never print ``` ## 2. Latest release ```sh git tag --list 'v[0-9]*.[0-9]*.[0-9]*' --sort=-v:refname | head -1 ``` Cross-check with the `mcp__github__get_latest_release` MCP tool (load it with ToolSearch first). If the tag and the GitHub release differ (a tag without a release is normal for the one in progress, a release without a tag is not), tell the user and ask before going on. With no tag at all, the first release is `v0.1.0`. While the Makefile has `release-gitea` (step 10), GitHub has no releases yet: cross-check with `mcp__gitea__get_latest_release` instead. ## 3. Changes since ```sh git log --format='%h %s%n%b---' ..HEAD git diff --stat ..HEAD ``` No commits since the last tag: stop, there is nothing to release. Read the commits, and where a subject is not clear, the diff. Sort each change as: - **breaking**: removes or changes a key, a command or flag, the on-disk or release contract (`install.sh`, asset names, `latest/download/VERSION`, `submarine update`), or behavior users rely on; - **feature**: a new key, action, view or option, or a visible behavior; - **fix / other**: bug fixes, docs, refactoring, tests, performance. ## 4. Next version | Changes include | Version `0.y.z` (current) | Version `≥ 1.0.0` | |---|---|---| | breaking | minor (`0.y+1.0`) | major | | feature | minor (`0.y+1.0`) | minor | | only fix / other | patch (`0.y.z+1`) | patch | submarine is below 1.0: the first release at `1.0.0` is a decision for the user, never made by this skill. Prepare a one-line reason per change and the proposed version. ## 5. Release check (before anything is tagged) All must pass; stop at the first failure and report its output. Nothing has been pushed yet, so there is nothing to undo. ```sh go vet ./... go test ./... test -z "$(gofmt -l .)" make dist VERSION=vX.Y.Z # all four platforms cross-compile ./dist/submarine_linux_amd64 version # prints "submarine vX.Y.Z" (run the one for this machine) make clean ``` Also check by reading: `README.md` and `docs/` mention the new behavior of the features in the changelog (AGENTS.md: keep docs in sync). A missing doc is a finding to report, not a reason to edit during a release; ask the user. `make dist` and `make clean` only touch the git-ignored `dist/`. ## 6. Confirm, then tag and push Ask the user (AskUserQuestion) to confirm the version, with the proposal first and marked `(Recommended)`, the other bumps as alternatives. Show: the last version, the changes with their category, the check result, and that the next step creates and pushes the tag. Only after the answer: ```sh git tag -a vX.Y.Z -m "vX.Y.Z" git push origin vX.Y.Z git ls-remote --tags origin vX.Y.Z # the tag is on the remote ``` If the push fails, report git's message. Do not retry with force. If the tag is wrong after it was pushed, ask before deleting it. ## 7. Write the release notes Write them to `/tmp/submarine-vX.Y.Z-notes.md` (outside the repository: `make release` refuses a dirty tree). They are for users of the tool, not a commit dump: short, grouped under **Breaking changes** (only if any), **New**, **Fixes** (leave out empty groups and pure refactoring/tests), each item one line naming the key or behavior (`b` switches the branch of a repository...). End with: ``` Install or update: `curl -fsSL https://raw.githubusercontent.com/simonfranken/submarine/main/install.sh | sh`, or `submarine update`. Full changelog: https://github.com/simonfranken/submarine/compare/...vX.Y.Z ``` Show the notes to the user; they can change them before the next step. ## 8. Hand over: the developer runs `make release` HEAD is now the clean tag, which is what `make release` needs. Tell the developer to run, in the repository: ```sh make release NOTES=/tmp/submarine-vX.Y.Z-notes.md ``` (it uses `gh`, tests, builds, creates the release as a draft with all assets and publishes it last). **Stop here and wait** until they say it finished. If it failed, help with the output; do not run it yourself. A leftover draft from a failed run must be deleted (ask first) before a retry. ## 9. Verify the release Once the developer reports success: ```sh curl -fsSL https://github.com/simonfranken/submarine/releases/latest/download/VERSION ``` must print `vX.Y.Z` (this is what `install.sh` and `submarine update` read). Check with `mcp__github__get_release_by_tag` that it is not a draft and has the assets `submarine_{linux,darwin}_{amd64,arm64}`, `checksums.txt` and `VERSION`. If anything is missing, report it. Finish with the link to the release and the version. ## 10. Bridge release (only while the Makefile has `release-gitea`) The first GitHub release is also published to the old Gitea registry, so binaries that still update from Gitea pick it up (D33). After step 9, and after asking the user, push the tag to the `gitea` remote and hand over again: ```sh git push gitea main vX.Y.Z make release-gitea # run by the developer, needs GITEA_TOKEN curl -fsS https://git.simon-franken.de/api/packages/simonfranken/generic/submarine-latest/latest/VERSION ``` The last command must print `vX.Y.Z`. Then create a Gitea release for the tag with `mcp__gitea__create_release`, its body saying that submarine moved to https://github.com/simonfranken/submarine.