Releasing AHP
This skill is the operational counterpart to RELEASING.md
and the cross-cutting AGENTS.md. RELEASING.md is the
canonical reference for what to do per artifact; this skill captures the
order of operations and the foot-guns that bite during a multi-artifact
release.
The repo ships seven independently-versioned artifacts but they are released
together by convention — pin the same X.Y.Z across all six client
manifests and the spec on every release unless the user explicitly asks
otherwise.
When to use this skill
The user wants to release AHP. Typical asks:
- "release AHP 0.3.0"
- "tag the release", "push the release tags", "run the publish workflows"
- "the next release will be X.Y.Z" (implies post-release bump)
- "the publish workflow didn't fire on tag T, can you re-trigger it"
If the user asks for a single-client release (e.g. "just bump Rust"),
prefer the .github/prompts/publish-*.prompt.md files instead — this skill
is for coordinated cross-artifact releases.
Mental model
A release is two commits in one PR, plus seven tags pushed at the first commit's SHA after CI and review approval but before merge:
- Release commit — consumes
docs/.changes/*.jsonfragments into dated## [X.Y.Z]CHANGELOG sections, bumps every client manifest from the previous version →X.Y.Z, and regeneratesrelease-metadata.jsonfor every client. All seven tags must point at this commit's SHA. - Post-release commit — bumps
PROTOCOL_VERSIONintypes/version/registry.tsto the next planned version, regenerates native version constants, adds an Unreleased spec changelog placeholder, and prepends the released version toSTABLE_DOC_VERSIONSindocs/.vitepress/versions.ts. Keep the released compatibility baselines inSUPPORTED_PROTOCOL_VERSIONSunchanged unless intentionally revising policy.
Create the bare Swift/docs tag locally before validating commit 2. Push tags only after the PR is approved and CI passes, then enable merge. Publishing therefore starts before merge, and the documentation deployment triggered by merge can resolve the new stable tag. No follow-up docs PR is needed.
Step-by-step
0. Capture the inputs
Before touching anything, confirm with the user:
- Release version (
X.Y.Z) — the version to use when consumingdocs/.changes/*.jsoninto the seven changelogs. - Next development version (default: bump minor, i.e.
X.(Y+1).0). - Release scope (default: all seven artifacts; rare to release one in isolation).
1. Branch + commit 1 (release commit)
Create release/ahp-<version> off main. Then in a single commit:
- CHANGELOGs — run
npm run changelog:release -- --version X.Y.Z --date <today YYYY-MM-DD>to collapsedocs/.changes/*.jsoninto the seven changelogs. This creates or replaces each## [X.Y.Z] — <today YYYY-MM-DD>section and adds theSpec version/Implements AHP X.Y.Z.line automatically. - Manifests — bump every native version file to
X.Y.Z:clients/rust/Cargo.toml[workspace.package].versionand theversion = "X.Y.Z"pins onahp-types/ahpinside[workspace.dependencies].clients/kotlin/gradle.propertiesVERSION_NAME.clients/typescript/package.jsonversion.clients/swift/VERSION(bare semver, novprefix, trailing newline).clients/go/VERSION(bare semver, novprefix, trailing newline).clients/dotnet/VERSION(bare semver, novprefix, trailing newline).
- Lockfiles — refresh after the manifest bump:
- In
clients/typescript/:npm install --no-audit --no-fund(no-op if already up to date but writes the version intopackage-lock.json). - In
clients/rust/:cargo update -w(rewrites only the workspace crates inCargo.lock— outside crates stay pinned).
- In
- Metadata — at repo root:
npm run generate:metadata. - Verify — at repo root:
npm test. This runsverify:change-fragments,verify:release-metadata, andverify:changelog, which together gate the release: malformed fragments, a metadata drift, or a missing CHANGELOG heading will fail here and not at tag-push time.
Do not bump
PROTOCOL_VERSIONin this commit. The tag-push workflows validate that the registry version matches the tag's version, so commit 1 must still havePROTOCOL_VERSION = X.Y.Z.
Commit message:
release: AHP X.Y.Z
Record this commit's SHA and create the bare Swift/docs tag locally. Every release tag points at this SHA. Do not push tags yet.
RELEASE_SHA=$(git rev-parse HEAD)
git tag vX.Y.Z "$RELEASE_SHA"
2. Commit 2 (post-release bump and docs promotion)
On the same branch, in a second commit:
types/version/registry.ts:PROTOCOL_VERSION = 'X.(Y+1).0'.- Leave
SUPPORTED_PROTOCOL_VERSIONSunchanged: it contains released compatibility baselines, not every release or development version.
- In
docs/.vitepress/versions.ts, prependX.Y.ZtoSTABLE_DOC_VERSIONS, keeping older entries. For example, releasing1.1.0and starting1.2.0setsPROTOCOL_VERSION = '1.2.0'andSTABLE_DOC_VERSIONS = ['1.1.0', '1.0.0']in this same commit. Both the homepage specification label and the default docs use the first stable entry; only the draft label followsPROTOCOL_VERSION. - Run
npm run generateat repo root — this regenerates every client'sVersion.generated.*and everyrelease-metadata.json. - In the root spec
CHANGELOG.md, add a## [X.(Y+1).0] — Unreleasedplaceholder (with aSpec version: \X.(Y+1).0`line) below the existing## [Unreleased]section. Per-client changelogs already keep their empty## [Unreleased]` section after fragment consumption. - Run
npm testandnpm run docs:build. The localvX.Y.Ztag from step 1 supplies the new stable snapshot. Verify the default release pages, older version routes, and next-development draft label.
Commit message:
chore: bump PROTOCOL_VERSION to X.(Y+1).0 for ongoing development
3. Open the PR and obtain approval (do not enable auto-merge yet)
git push -u origin release/ahp-X.Y.Z
gh pr create --base main --head release/ahp-X.Y.Z \
--title "release: AHP X.Y.Z" \
--body-file <(...)
Wait for all required CI checks and collaborator approvals. Confirm merge commits are allowed; otherwise stop and agree on a release strategy before publishing tags. Do not push release tags while the PR still needs changes. If either commit changes, revalidate the release SHA and docs build before continuing; never move an already-published tag.
The PR body should include:
- The release SHA in a copy-pastable variable assignment.
- The seven tag-push commands (see step 4 below), noting that they must run before auto-merge is enabled.
- The docs promotion and successful
npm run docs:buildvalidation. - A note that Kotlin, TypeScript, and .NET publish via Azure DevOps pipelines (they appear under agent-host-protocol pipelines in vscode-engineering), not GitHub Actions.
4. Push the seven tags before merge
The PR must be approved and CI green before this step: pushing these tags
starts publishing from the validated release commit before it reaches main.
The bare vX.Y.Z tag was already created locally in step 1.
RELEASE_SHA=<sha from step 1>
git tag spec/vX.Y.Z "$RELEASE_SHA"
git tag rust/vX.Y.Z "$RELEASE_SHA"
git tag kotlin/vX.Y.Z "$RELEASE_SHA"
git tag typescript/vX.Y.Z "$RELEASE_SHA"
git tag clients/go/vX.Y.Z "$RELEASE_SHA"
git tag dotnet/vX.Y.Z "$RELEASE_SHA"
git push origin spec/vX.Y.Z
git push origin rust/vX.Y.Z
git push origin kotlin/vX.Y.Z
git push origin typescript/vX.Y.Z
git push origin vX.Y.Z
git push origin clients/go/vX.Y.Z
git push origin dotnet/vX.Y.Z
git ls-remote --tags origin '*/vX.Y.Z' 'vX.Y.Z'
Verify all seven remote tags point at RELEASE_SHA before enabling merge.
Push tags separately so each emits its own publish event.
The seven tag schemes are deliberate and not interchangeable. Bare
vX.Y.Z is reserved for Swift (SwiftPM only resolves root-level tags);
clients/go/vX.Y.Z is required by the Go module proxy's sub-module
resolution.
5. Confirm publish runs started
For each tag, verify the corresponding workflow run is queued or in progress:
GH_PAGER=cat gh run list --limit 10 \
--json databaseId,event,headBranch,status,conclusion,workflowName,displayTitle
Expect to see four GH Actions runs (one per tag below) within seconds:
| Tag | Workflow | Publishes to |
|---|---|---|
spec/vX.Y.Z |
Publish Spec |
GitHub Release (schema assets) |
rust/vX.Y.Z |
Publish Rust Crates |
crates.io (ahp-types, ahp, ahp-ws) |
vX.Y.Z |
Publish Swift Package |
SwiftPM (tag-resolved) |
clients/go/vX.Y.Z |
Publish Go Module |
Go module proxy (tag-resolved) |
The remaining three tags trigger Azure DevOps pipelines that don't appear
in gh run list:
| Tag | ADO Pipeline | Publishes to |
|---|---|---|
kotlin/vX.Y.Z |
clients/kotlin/pipeline.yml |
Maven Central via ESRP |
typescript/vX.Y.Z |
clients/typescript/pipeline.yml |
npm via ESRP |
dotnet/vX.Y.Z |
clients/dotnet/pipeline.yml |
NuGet.org via ESRP (approval required) |
For Kotlin/TypeScript/.NET, link the user to the AHP pipelines in ADO
(vscode-engineering tenant) to confirm the runs started. These
pipelines can also be triggered manually from the ADO UI as a hotfix
escape hatch — the validation steps inside each pipeline are identical
to the tag-triggered path.
6. Merge the combined PR and verify the deployed website
Only after all remote tags are verified and publish runs have started:
gh pr merge <num> --auto --merge
Use --merge, not --squash or rebase-and-merge, to keep the tagged release
SHA reachable from main.
After merge:
git fetch origin main
git merge-base --is-ancestor "$RELEASE_SHA" origin/main
Do not tag the post-release commit: its registry is already on the next
development version. Wait for Deploy Documentation to succeed, then verify
the live homepage shows vX.Y.Z, default docs use X.Y.Z, the version selector
includes older stable releases, and only the next development version is
labelled (draft). Track publish approvals/failures explicitly. Do not mark the
release complete based only on package publication or a local docs build.
Recovery — tag pushed but no publish run fired
This has happened. Symptom: tag exists on origin but gh run list
shows no corresponding workflow run.
None of the four GH Actions publish workflows currently declare
workflow_dispatch, so manual dispatch is not available. The recovery
is to delete the remote tag and re-push it at the same SHA — this
emits a fresh push event without changing the tagged commit:
git push origin --delete <tag>
git push origin <tag>
Do not include the --deleted tag in the same git push command as
the re-push — push them in separate git push invocations so each tag
emits its own push event. Re-pushing several tags in a single command
sometimes coalesces into a single event and only one workflow fires.
Once recovery is verified, suggest a follow-up PR adding
workflow_dispatch: to the four publish workflows so the next missed
trigger can be re-run from the Actions UI without tag thrash.
Common foot-guns
- Deferring docs promotion or merging before tags exist — update
STABLE_DOC_VERSIONSalongside the development bump in the same PR. Create the bare tag locally for validation, push it after CI/review approval, and only then enable merge. Otherwise the website stays on the old release or its build cannot resolve the new snapshot. - GPG signing lock during
git commit— if you seegpg: keydb_search failed: Operation timed out, rungpgconf --kill all && rm -f ~/.gnupg/public-keys.d/pubring.db.lockand retry the commit. - Bumping
PROTOCOL_VERSIONin commit 1 — the publish workflows re-validate the tag against the tagged commit'sPROTOCOL_VERSION, so a release tag pointing at the post-release commit fails the "Verify tag matches" step. Always keep the bump in commit 2. - Forgetting the Rust
[workspace.dependencies]pins — bumping just[workspace.package].versionleaves the cross-crateahp-types/ahppins on the old version.verify-release-metadatadoes not catch this butcargo publish --dry-runwill. - Forgetting
cargo update -w— without it,Cargo.lockkeeps the old version for ahp-types/ahp/ahp-ws and the resulting commit is partially-bumped. CI's per-language drift check catches it. - Forgetting the Swift/Go trailing newline in
VERSION— theread*PackageVersionhelpers trim, so functionally it's fine, but the convention is0.3.0\n. - Mixing up the Swift tag namespace — Swift uses bare
vX.Y.Z(no prefix). Every other artifact has a prefix. Puttingswift/vX.Y.Zon Swift's tag silently breaks SwiftPM resolution.