agentleFS
NVIDIAKnown publisherNVIDIA/k8s-test-infra/.claude/skills/release/SKILL.md

release

Skill115 starsChanged 5 days agoApache-2.0View on GitHub

Run a Mokka (NVIDIA/k8s-test-infra) release end to end. Covers the release-prep PR (changelog fold), merge, signed tag, publish pipeline checks, `make verify-release`, the GitHub release notes, the stacked chart bump to the next -dev version, and the Slack announcement draft. Use this whenever the user wants to cut, prepare, tag, publish, verify or announce a Mokka release, says "release 0.7.0", "prepare v0.7.0", "fold the changelog for the release", "push the tag", "create the GitHub release", "bump the charts after the release" or "draft the release announcement", or picks up a release that is already partway done. Also use it for an out-of-cycle patch release (vX.Y.Z) and for a security release that fixes a CVE, GHSA or Go vulnerability ("cut a security release", "ship the fix for GHSA-…").

  • Commits and pushes

193 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use create-agent-adapter, changelog-style and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MicrosoftSkill

    create-agent-adapter

    Technical guide for creating a new Paperclip agent adapter. Use when building a new adapter package, adding support for a new AI coding tool (e.g. a new CLI agent, API-based agent, or custom process), or when modifying the adapter system. Covers the required interfaces, module structure, registration points, and conventions derived from the existing claude-local and codex-local adapters.

    Also in 5 projects that use this

  • GrinvSkill

    changelog-style

    Turn a commit range into CHANGELOG.md entries following common-changelog style. Use when finishing a PR or cutting a release, to write/fix the [Unreleased] section's entries — moving [Unreleased] under a new dated version heading is a separate, automated step (see the release skill / scripts/sync-version.ts), not this skill's job.

    Also in 4 projects that use this

  • GrinvSkill

    docs-consistency-check

    Check README/manifest.json/server.json/CHANGELOG.md/AGENTS.md and docs/*.md for drift against the actual registered tools and source. Use after adding, renaming, or removing a tool, or as part of a live-audit pass.

    Also in 4 projects that use this

  • Microsoft AzureSkill

    component-release

    Prepares a verifiable Agent Landing Zone UI release. Use for release branches, VERSION, changelog entries, tags, release notes, and compatibility evidence; never publish without explicit human approval.

    Also in 4 projects that use this

  • Microsoft AzureSkill

    documentation-consistency

    Keeps AI Landing Zone contributor, user, and operator documentation aligned with shipped Bicep behavior. Use for parameters, defaults, outputs, topology, deployment flow, operations, or releases.

    Also in 8 projects that use this

  • rivet-devSkill

    launch-graphics

    Generate agentOS marketing/launch graphics (launch & social heroes, code-snippet cards) from the committed generators in docs-internal/graphics. Use when asked to make, update, or render an agentOS launch image, social image, "agentOS Apps" graphic, or technical code-snippet image.

    Also in 3 projects that use this

  • +3 more from Grinv

The file

Show its rules and text

We split this skill into the rules it gives an agent

22 rules. 0 are common, 5 are distinctive, and 17 are very specific to this project.

  • 0

    Common

    Most of the 183 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 17

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Sign everything: Use git commit -s -S, git rebase --signoff -S and git tag -s.

    line 31
  2. Very specific:

    Write version numbers without the v for images, charts, CHANGELOG headings and make targets (0.7.0).

    line 39
  3. Very specific:

    If the go directive in go.mod rose since the last tag, the notes state the new minimum Go version.

    line 64
  4. Very specific:

    Check that every released version has its section in main's CHANGELOG.md: git show vA.B.C:CHANGELOG.md against main.

    line 79
  5. Distinctive:

    Remove fragments that describe states no release shipped, such as fixes to a feature that is new in this release.

    line 94
  6. Very specific:

    Every breaking change starts with Breaking: and states the user's action.

    line 97
  7. Very specific:

    Every Removed entry needs a deprecation announced three Y releases earlier.

    line 99
  8. Very specific:

    Check a fix against the previous tag (git grep … vA.B.C -- …) before deciding that it fixes something released.

    line 102
  9. Distinctive:

    Commit these edits with a body that lists each removal and the reason.

    line 104
  10. Very specific:

    Fold: run make changelog-preview RELEASE_VERSION=X.Y.Z, then make changelog-release RELEASE_VERSION=X.Y.Z.

    line 105
  11. Very specific:

    Charts: leave Chart.yaml unchanged, at X.Y.0-dev.

    line 110
  12. Very specific:

    Gates: run make helm-tests, make helm-crds-tests, make lint, make build and make test.

    line 117
  13. Very specific:

    Run make helm-tests, make helm-crds-tests and go test ./tests/hack/....

    line 136
  14. Very specific:

    Write the PR bodies with .github/pull_request_template.md.

    line 152
  15. Distinctive:

    Merge the prep PR: only with approval and green checks, after the user confirms.

    line 159
  16. Very specific:

    CI must be green on the prep merge commit: before tagging: gh run list --workflow "CI Pipeline" --commit <merge-sha>.

    line 168
  17. Very specific:

    Never push an -rc or other non-stable tag.

    line 185
  18. Very specific:

    If a publish run failed, read its log (gh run view <id> --log-failed) before acting.

    line 203
  19. Distinctive:

    Late fragments first: If Phase 3 listed fragments, follow the template's "After the release" item before writing any notes: a PR against …

    line 209
  20. Very specific:

    Run it from a checkout of the merged main, because it reads the release's section from CHANGELOG.md.

    line 227
  21. Very specific:

    If the user wants the release out before the publish runs finish, create it with the digests that are final, mark the rest as pending, and …

    line 242
  22. Very specific:

    Update the tracking issue with the tag, the release link, the verify-release output and the changelog section, then close it.

    line 250

“Common” is measured: kept by at least 6 in 10 of the 183 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Mokka release

A release takes main to published, signed images and charts plus a GitHub release. Every release is cut from main, security releases included: docs/support-policy.md allows no release branches and no backports, so a fix ships from main and users upgrade to it. The repository's own checklists are the source of truth: .github/ISSUE_TEMPLATE/release.yml (scheduled vX.Y.0) and .github/ISSUE_TEMPLATE/patch_release.yml (out-of-cycle). Read the one that applies at the start, because it can change between releases and wins over this skill. This skill adds the order of operations, the commands, and the lessons from earlier releases (see references/gotchas.md).

Ground rules

  • Find out where the release stands first. A release spans hours and often more than one session. Before doing anything, check: does a vX.Y.Z tag exist (git ls-remote --tags upstream)? Is there a GitHub release (gh release view)? Is there an open or merged prep PR? Is there a tracking issue? Then resume at the first unfinished phase.
  • Confirm each outward step. Merging, pushing a tag, creating the GitHub release and closing PRs are visible to everyone, and a pushed tag starts publishing artefacts that cannot be unpublished. Get a yes for each one, even when the user asked for the whole release. A yes for one step does not cover the next.
  • Sign everything. Use git commit -s -S, git rebase --signoff -S and git tag -s. If signing fails, stop and report it. Never fall back to unsigned.
  • Remotes. upstream is NVIDIA/k8s-test-infra and origin is the user's fork. The local main is usually stale, so always base work on upstream/main after git fetch upstream --tags.
  • Use a dedicated worktree for the release branch, so the user's other checkouts are untouched.
  • Write version numbers without the v for images, charts, CHANGELOG headings and make targets (0.7.0). Use the v only for git tags (v0.7.0).

Security releases

A security release is an out-of-cycle release whose reason is "Security". It runs the same phases with patch_release.yml, plus:

  • Cut it from main, not from the previous tag. The fix merges to main first. If main also carries non-fix changes since the last tag, the version check makes it the next Y, and the release notes say it shipped ahead of the schedule. If the user wants to release from an older tag or a release/X.Y branch instead, stop: that changes the support policy, and the publish workflows and make verify-release assume a tag on main's history.
  • Keep an undisclosed vulnerability private. Advisories that are already public (a dependency CVE, a GO- entry) go in the issue, the tag message and the notes, as the template asks. For a vulnerability reported privately (a draft GHSA or psirt@nvidia.com), ask the user what may be public before writing it into any issue, PR, commit, tag message or Slack draft, and publish nothing about it before the advisory goes out.
  • govulncheck on a checkout of the last tag and of the base commit, with CI's Go toolchain (references/gotchas.md, "Local gates on macOS"). The base commit must report none of the listed advisories. If the release spans more than one day, rerun it on the base commit on the day of tagging. Paste every output in the issue.
  • If the go directive in go.mod rose since the last tag, the notes state the new minimum Go version.
  • The prep PR keeps the Security changelog entries. The tag message, the release notes' summary and the Slack draft name each fix and its advisory ID, and tell users to upgrade, since older releases get no fix.
  • For a Z release, skip Phase 2: main's charts are already at the next minor's -dev. Confirm it, and merge the last bump PR first if it is still open.

Phase 0: Plan

  1. Work out the version. A scheduled release bumps Y. For a patch release, follow the version check in patch_release.yml: it is the next Z only when every change since the last tag is a fix.
  2. Find the previous release, which is the latest stable tag on any branch. Check that every released version has its section in main's CHANGELOG.md: git show vA.B.C:CHANGELOG.md against main. A patch cut from a release branch may never have been ported (v0.5.1 was not). Port a missing section and its compare link in the prep PR, and delete any fragment that release already shipped, so the new notes don't repeat it.
  3. Record the base commit, upstream/main. Offer to open the tracking issue from the matching template, but only open it if the user agrees.

Phase 1: Release-prep PR

Branch from upstream/main in a new worktree.

  1. Review the fragments in .changes/unreleased/ before folding. The notes tell a user of the previous release what changed for them. Apply the rules in AGENTS.md ("Changelog") and the pre-flight checks in the template:
    • Remove fragments that describe states no release shipped, such as fixes to a feature that is new in this release. Also remove fragments for build-time-only tools, refactors and CI, which users never run.
    • Every breaking change starts with **Breaking:** and states the user's action.
    • Every Removed entry needs a deprecation announced three Y releases earlier. Don't silently drop or keep one that fails this: flag it in the PR for the release engineer.
    • Check a fix against the previous tag (git grep … vA.B.C -- …) before deciding that it fixes something released.
    • Commit these edits with a body that lists each removal and the reason.
  2. Fold: run make changelog-preview RELEASE_VERSION=X.Y.Z, then make changelog-release RELEASE_VERSION=X.Y.Z. Add the compare link [X.Y.Z]: …/compare/vPREV...vX.Y.Z above the previous one. Count the fragments the fold removed and the bullets in the new section; the two counts must match, and both go in the PR.
  3. Charts: leave Chart.yaml unchanged, at X.Y.0-dev. The tag sets the published version and appVersion, and main refuses to publish a non--dev chart version (hack/chart-publish-version.sh). Setting it to X.Y.Z here breaks every publish run on main until the bump PR lands.
  4. Docs pins: git grep -nF '<previous-version>' -- docs. Since #1081 the docs don't pin Mokka. Most hits are other projects' versions (DRA driver chart), minimum versions, or "last validated with" records. Leave those.
  5. Gates: run make helm-tests, make helm-crds-tests, make lint, make build and make test. On macOS, read references/gotchas.md ("Local gates on macOS") before reporting a failure.
  6. Squash into one commit, chore(release): prepare vX.Y.Z, unless the user wants the steps as separate commits.

Phase 2: Chart bump, stacked on the prep PR

On a branch on top of the prep branch, bump both charts (deployments/nvml-mock/helm/nvml-mock/Chart.yaml and deployments/mokka-crds/helm/mokka-crds/Chart.yaml) version and appVersion to the next minor's -dev (0.8.0-dev after v0.7.0). Also update the -dev example in docs/helm-chart.md. Commit it as chore(release): bump the charts to X.Y+1.0-dev.

Mokka has no application version in Go code. The CDIVersion: "0.6.0" strings in internal/agent/cri and internal/nri are the CDI spec version, so leave them alone.

Run make helm-tests, make helm-crds-tests and go test ./tests/hack/....

Open both PRs as a GitHub stack with gh-stack. The branches must be in upstream, because a stack bases each PR on the branch below it:

gh stack init --base main <prep-branch> <bump-branch>
GH_STACK_NO_UPDATE_NOTIFIER=1 gh stack submit --auto --remote upstream </dev/null

--auto creates drafts with generated titles. Afterwards, set each PR's title, body and the skip-changelog label with gh pr edit. gh stack init attaches any existing PR whose head branch has the same name, fork PRs included. If that happens, run gh stack unstack --local, rename the branches, and init again. Later pushes go through gh stack push --remote upstream.

Write the PR bodies with .github/pull_request_template.md. The prep PR's body covers the fragment corrections with reasons, the fold counts, gate results, and a "For the release engineer" list of anything that needs a decision. The bump PR says it merges after the tag.

Phase 3: Merge and tag

  1. Merge the prep PR only with approval and green checks, after the user confirms. Don't rebase it just because main moved: every push dismisses approvals, and a PR that is behind main still merges. Rebase only when it gets the needs-rebase label (git rebase --signoff -S upstream/main), then rebase the bump branch onto the new prep head, check that every commit is still signed (git cat-file -p <sha> | grep -q '^gpgsig') and gh stack push --remote upstream. Fragments that merged after the fold stay out of the prep PR: step 3 lists them and Phase 5 moves them into the changelog.
  2. CI must be green on the prep merge commit before tagging: gh run list --workflow "CI Pipeline" --commit <merge-sha>. Watch it with gh run watch <id> --exit-status in the background. If the user wants to tag before CI finishes, say what that risks and let them decide.
  3. List the fragments that merged after the base commit: git diff --name-only --diff-filter=A <base> <merge-sha> -- .changes/unreleased. Paste the list in the issue, even when it is empty.
  4. Tag the merge commit, given explicitly, with a signed annotated tag. The message has a one-paragraph headline and the breaking changes with their actions:

    git tag -s -F <message-file> vX.Y.Z <merge-sha>
    git cat-file -p vX.Y.Z | head -5   # check: object is <merge-sha>, type commit
    git push upstream vX.Y.Z

    Never push an -rc or other non-stable tag; every publish workflow refuses it. Pushing the tag needs bypass on the tag ruleset.

Phase 4: Check the tag pipeline

Three runs start from the tag: nvml-mock Publish, Mokka Control Plane Publish and helm-publish (gh run list --branch vX.Y.Z). Watch them in the background. When all three succeed, run:

make verify-release RELEASE_VERSION=X.Y.Z

It checks the runs, platforms, X.Y and latest tags, chart versions, every cosign signature and every SBOM attestation. Every line must be ok:. Keep the output for the issue.

If a publish run failed, read its log (gh run view <id> --log-failed) before acting. references/gotchas.md has the known failures. Before rerunning, check that nobody else already did: gh run view <id> --json attempt,status.

Phase 5: GitHub release

  1. Late fragments first. If Phase 3 listed fragments, follow the template's "After the release" item before writing any notes: a PR against main moves each listed fragment's entry into this release's section of CHANGELOG.md, under its kind heading, and deletes the fragment. It also adds a missing **Breaking:** marker and user action. Paste the three counts (folded, listed, bullets in the section) in the PR and apply skip-changelog. Merge it after the user confirms. Skip this step when the list was empty.
  2. Then create the release, once that PR has merged (or right after the tag when the list was empty). Otherwise the notes miss shipped changes, breaking ones included.

Render the notes from the published artefacts:

.claude/skills/release/scripts/release-notes.sh X.Y.Z > <scratch>/notes.md

Run it from a checkout of the merged main, because it reads the release's section from CHANGELOG.md. Replace the SUMMARY line with two short paragraphs:

  • the headline changes, by component, in plain words;
  • "Upgrading:" with the helm upgrade target, the number of Breaking: entries to read first, and any default the user should know about, such as a feature gate that is on by default and reaches the internet.

Then:

gh release create vX.Y.Z -R NVIDIA/k8s-test-infra --verify-tag --latest \
  --title vX.Y.Z --notes-file <scratch>/notes.md

If the user wants the release out before the publish runs finish, create it with the digests that are final, mark the rest as pending, and finish with gh release edit --notes-file once verify-release passes. Never invent a digest.

Phase 6: After the release

  • Merge the stacked chart bump PR soon after the tag.
  • Update the tracking issue with the tag, the release link, the verify-release output and the changelog section, then close it.

Phase 7: Slack announcement

Draft the message for the user to paste; don't post it. Use Slack mrkdwn (*bold*, • bullets, backticks), keep it to about 15 lines, and build it from the release notes. references/gotchas.md ("Slack template") has the shape. Link the GitHub release, which exists by now.

Reporting

At each pause, say what is done (with SHAs, PR numbers and URLs), what is running, and the next step that needs the user. When a step was skipped or ran against the checklist (tagging before green CI, for example), say so plainly.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.