aicr-release-notes

# AICR Release Notes Draft Generates the user-facing release notes summary that goes into the GitHub Releases body (e.g. <https://github.com/NVIDIA/aicr/releases/tag/v0.13.0>), NOT the raw `tools/changelog` commit list that already appears below the summary. Output is a draft — the author hand-edits before publishing. ## When to Use - User asks to draft release notes, release summary, or release announcement - User invokes `/aicr-release-notes` - A tag is about to be cut and the maintainer needs the highlights paragraph Do NOT use this skill to publish a release, push a tag, or edit `CHANGELOG.md`. It only writes a Markdown draft to a temp file. ## Inputs `tools/changelog` is the single source of truth for: - Which tag range is being summarized (it picks the latest stable tag and prints `[MSG] Changes since vX.Y.Z` to stderr). - The set of commits to consider. - The author handle for every commit (already rendered as `by [@handle](https://github.com/handle)` at the end of each line). Do NOT re-derive any of this with separate `git log`, `gh api`, or `gh pr list` calls. If `tools/changelog` doesn't surface it, it doesn't belong in the summary. No optional input is needed. Do not ask for or guess the target tag — the filename is fixed (see Step 5) and the body never names the new tag (GitHub renders the tag in the release header). ## Procedure ### Step 1 — Gather raw material Run in parallel: ```bash # Commit list since last stable tag — single source of truth tools/changelog # Previous release body for style mirroring (use the tag from # tools/changelog's "[MSG] Changes since vX.Y.Z" stderr line) gh release view <previous-tag> --json body --jq '.body' ``` If `tools/changelog` errors ("No release tags found", empty output), stop and ask the user how to proceed — do not invent a range. ### Step 2 — Classify commits into themes Read every line of `tools/changelog` output. Group by **user-visible impact**, NOT by conventional-commit scope. The goal is a release-notes narrative, not a mirror of `git log`. Useful theme buckets, in rough priority order: 1. **Headline feature** — the single most significant new capability (often a new command, a new deployer, a new contract). Open paragraph should name 3–4 of these inline as bolded phrases. 2. **New deployer / output target** — bundler additions, new packaging. 3. **Recipes & overlays** — new accelerator/service/intent combinations, new mixins. Use a bulleted sub-list when there are 3+. 4. **Validation / evidence / supply chain** — anything that strengthens trust: BOM, SBOM, signing, evidence verification, conformance. 5. **Docs / DX** — new doc site features, CLI ergonomics, config unification. 6. **Other improvements** — collect leftover user-visible wins. **Exclude from the narrative** (they still appear in the raw changelog below the summary on the GitHub release page): - `deps:` bumps and Renovate/Dependabot lines - CI plumbing that doesn't change developer experience - Pure refactors with no user-visible effect UNLESS the cumulative effect is a public API surface change worth flagging (e.g. "Per-Builder DataProvider isolation" got a mention because it's a contract change for embedders of `pkg/client/v1` / `pkg/aicr`) - Test-only changes - Doc-style fixups ### Step 3 — Draft the Markdown Match the exact structure of the previous release. Required sections, in order: 1. **Opening paragraph** — one sentence. "This release focuses on …, …, …, and …." Each major theme is `**bolded**` inline. No heading above it. 2. **`### Highlights`** — heading exactly as written. 3. **`**Theme Name**` blocks** — each starts with bolded title, em dash (` — `, with spaces), then 1–3 sentences OR a bulleted sub-list. Use sub-lists when enumerating 3+ concrete items (e.g. recipes added). 4. **`### Deprecations`** — **required whenever the release deprecates or removes anything on the four frozen surfaces** (CLI, REST, Go SDK, bundle and artifact schemas); omit the heading entirely when it does not. One bullet per item: what is deprecated, the replacement, and the release that removes it. This is a release-blocking section, not a courtesy — see the [deprecation policy](https://github.com/NVIDIA/aicr/blob/main/RELEASE.md#deprecation-policy). Every bullet here must also have an entry in `docs/user/deprecations.md`; if it does not, the deprecation is incomplete and the release is not ready. 5. **Closing credits line** — `***Thanks to*** @user1, @user2, …, and @mchmarny.` Alphabetical (case-insensitive) by handle, with `@mchmarny` moved to the final position preceded by `and `. **Style rules** drawn from prior releases: - Issue/PR references use `[NVIDIA/aicr#NNN](https://github.com/NVIDIA/aicr/issues/NNN)` form, NOT a bare `#NNN`. - External product links use full URLs in markdown (`[docs.nvidia.com/aicr](https://docs.nvidia.com/aicr)`). - Backtick CLI commands: `` `aicr validate` ``, `` `aicr evidence verify` ``. - Use em dashes (` — `) not hyphens for the inline definition pattern. - No emoji. No "What's Changed" heading. No version-comparison link (GitHub adds those automatically). - Keep total length comparable to the previous release (~250–400 words in the summary, not counting the auto-appended changelog). ### Step 4 — Build the contributor list The thanks line comes **entirely** from the `by [@handle](...)` annotations already present in `tools/changelog` output. Extract every unique `@handle` with a simple grep/awk over the changelog text: ```bash tools/changelog 2>/dev/null \ | grep -oE 'by \[@[^]]+\]' \ | sed -E 's/by \[@//; s/\]$//' \ | sort -uf \ | grep -viE '\[bot$' ``` Note the `[^]]+` capture stops at the FIRST `]`, so handles like `dependabot[bot]` come out as `dependabot[bot` (no trailing `]`). The final `grep -viE '\[bot$'` accounts for this — do NOT change it to `'\[bot\]$'` or bots will leak into the thanks line. Then: - Drop any handle ending in `[bot` after extraction (bot accounts: `dependabot[bot]`, `github-actions[bot]`, `renovate[bot]`, `copy-pr-bot`, etc.). - Sort alphabetically (case-insensitive). - Move `mchmarny` to the final slot preceded by `and `. - Do NOT link the @-mentions in the output — GitHub auto-links them. ### Step 5 — Write the draft Write to `$TMPDIR/aicr-release-notes.md` — fixed filename, no version suffix. Do NOT write under the repo tree — this is a hand-edit draft, not a checked-in artifact. Overwrite any prior draft at that path. **Append an "Unresolved questions for hand-edit" section at the bottom of the file**, separated from the credits line by a horizontal rule (`---`). The author edits the file directly, so questions belong in the file, not in chat. Typical content: - Calls the author should make about emphasis (e.g., "should the X bump be promoted to a highlight?") - Things to verify before publishing (issue references, feature completeness, prior-release framing) - Anything the skill chose to omit that the author may want back Format the section as: ```markdown --- ## Unresolved questions for hand-edit 1. **<topic>** — <one-or-two sentence note explaining the call to make> 2. **<topic>** — <…> ``` This section is for the author's eyes only and gets deleted before publishing. After writing, print to chat: 1. A ready-to-run macOS clipboard command on its own line in a fenced bash block: `pbcopy < <absolute-path>`. The user copies that line, runs it, and pastes into the GitHub release form. Do not print the bare path on a separate line — the `pbcopy` form is the path. 2. A one-line summary of which themes the draft surfaced (so the user can quickly tell if you missed something). Do NOT cat the full draft back into chat — the user will open the file directly. Do NOT print the unresolved questions separately — they are already in the file. ## Output Format Reference The structure to mirror, with placeholders: ```markdown This release focuses on <theme-1-bolded>, <theme-2-bolded>, <theme-3-bolded>, and <theme-4-bolded>. ### Highlights **<Theme 1 Title>** — <1–3 sentence narrative explaining what shipped and why it matters to a user. Reference commands in backticks. Link issues as [NVIDIA/aicr#NNN](https://github.com/NVIDIA/aicr/issues/NNN).> **<Theme 2 Title>** — <narrative> **<Theme with enumerated items>** * <Concrete item 1> * <Concrete item 2> * <Concrete item 3> **Other Improvements** * <Leftover user-visible win 1> * <Leftover user-visible win 2> **<Supply Chain or Trust Theme>** — <narrative> ***Thanks to*** @alice, @bob, @carol, and @mchmarny. ``` ## Failure Modes - **`tools/changelog` is empty** — likely the tag already exists or `LAST_TAG..HEAD` is empty. Ask the user which range to summarize. - **`gh release view` fails** — the previous tag may not have a release yet. Fall back to reading the README's recent-releases section or ask the user to point at a reference release for style. - **Repo state has uncommitted changes** — fine, `tools/changelog` only reads git history. No need to stash. ## What This Skill Does NOT Do - Does not run `git tag` or push tags - Does not create the GitHub release - Does not edit `CHANGELOG.md` or any in-repo file - Does not re-derive commit ranges, author handles, or commit lists outside of `tools/changelog` output