diff --git a/.agents/skills/release/SKILL.md b/.agents/skills/release/SKILL.md new file mode 100644 index 0000000..6cfdf31 --- /dev/null +++ b/.agents/skills/release/SKILL.md @@ -0,0 +1,62 @@ +--- +name: release +description: Release the Jetstream client SDK by updating its version and changelog, checking it, committing, tagging, and pushing to Tangled. +--- + +Release this repository. Use the version or scope Nate specifies. + +## Prepare + +- Inspect `git status`, the current branch, origin, and remote release tags. + Compare the candidate against the latest release tag, including commits + already on main and uncommitted changes. `git diff main` alone misses + unreleased commits on main. +- Keep unrelated working changes out of the release commit. Review them + before deciding which files or hunks to stage; never use `git add .` to + sweep them in. Do not discard them or check out an older version over them. +- Honor Nate's selected bump. Otherwise use patch for fixes and maintenance, + minor for new features or public API changes, and describe compatibility + changes explicitly. A dependency's minor bump does not itself dictate this + package's bump; inspect the effect on consumers. +- Update `.version` in `build.zig.zon` and add `## x.y.z` at the top of + `CHANGELOG.md`. Cover the full diff since the previous tag in the existing + terse style. Check README install examples for obsolete version pins. + +## Verify + +- Run `zig fmt --check` on the release's Zig/ZON files, `git diff --check`, + `zig build test --summary all`, and `zig build` to compile the examples. + Report test execution time separately from compilation time. +- The default tests include tiny loopback archive, cutover, failover, and + stall fixtures. Keep them local and bounded. The fake server must answer + shutdown requests and stop reading on EOF, or cleanup can mask failures + behind HTTP retries and busy loops. +- For transport or live-client changes, run the built + `zig-out/bin/example-failover-smoke https://stream.waow.tech` with an + external 30-second process timeout. It stops after ten live events. + Do not use archive cutover or whole-history examples as routine release + smokes; they can download substantial data. Report live-network failures + separately from local failures and resolve them before publishing. +- Verify checks cover the exact files being committed. When unrelated + working edits affect the build, test a separate temporary checkout of the + proposed release tree rather than treating those results as release proof. + +## Publish + +An explicit request to release this Jetstream client authorizes its release +commit, tag, and push. A request to prepare a release or create this skill +does not. If publication is not already authorized, finish the local +candidate and present its version, changes, and check results for approval. + +- Commit only the reviewed release files as `release: vx.y.z`. +- Confirm the candidate is on the intended release branch and the tag does + not already exist locally or remotely. Never move an existing release tag + or force-push to resolve a rejection. +- Tag the verified release commit with `vx.y.z`. Push the intended branch + and that exact tag to origin; do not use `--tags`, which can publish + unrelated local tags. Prefer an atomic push when supported. If the push + fails or its result is uncertain, inspect remote refs before retrying. +- Confirm the remote branch and tag resolve to the release commit. If this + repository has Tangled CI, use the Tangled skill to check its verdict. +- Report the version, commit, checks, and publication result. Updating + consumers or publishing in sibling repositories requires its own scope.