release-notes

# Release Notes Generator Generate polished, user-facing release notes for Intelligent Terminal releases by analyzing git history, PR metadata, and issue links. ## When to Use This Skill - User asks to write release notes or changelog - User asks "what's new since last release" - User asks to prepare a release - User asks to summarize recent commits for end-users ## Step-by-Step Workflow ### Phase 1: Identify the Commit Range The base is the **latest release tag** (the `vX.Y.Z` sequence, e.g. `v0.1.18`) and the head is **`main`**. The range is everything between them. 1. Find the **latest release tag** — the newest 3-part `vX.Y.Z` tag that is merged into `main`. The filter is what keeps this reliable: it excludes upstream Windows Terminal `v1.x` tags (not on this fork's history) and the legacy four-part `v0.1.NNNN.0` tags (stale, some point at ancient upstream commits). Do **not** anchor on `stable` — it is a cherry-picked subset that lags the release tag. ```bash git tag --list 'v*' --merged main --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1 ``` ```powershell git tag --list 'v*' --merged main | Where-Object { $_ -match '^v\d+\.\d+\.\d+$' } | Sort-Object { [version]($_ -replace '^v','') } | Select-Object -Last 1 ``` (The user may override with a specific base commit/tag; if the plain `git tag` list looks nothing like the above — e.g. only `v1.x` shows up — the `--merged main` filter is being skipped.) 2. List all commits from the base tag to `main` (replace `$BASE_TAG` with the tag from step 1): ```bash git log --oneline --reverse "$BASE_TAG"..main ``` 3. Extract PR numbers from commit messages (pattern: `(#NNN)`). > The `0.1.xxxx.0` build number is injected by CI at release time; the human-facing version is the `vX.Y.Z` tag sequence. ### Phase 2: Enrich with PR Metadata For each PR number, look up linked issues and author info (replace `PR_NUMBER` and `OWNER/REPO`): ```bash gh pr view PR_NUMBER --repo OWNER/REPO --json number,title,body,author,closingIssuesReferences ``` > Use `OWNER/REPO` = `microsoft/intelligent-terminal` for this repo's own PRs — they live on the canonical repo even when you're working from a fork/clone — or `microsoft/terminal` for upstream `#20xxx` PRs. To batch this lookup across many PRs at once, run [`scripts/Get-PrMetadata.ps1`](./scripts/Get-PrMetadata.ps1) with a list of PR numbers — it reports linked issues and flags community contributors (authors not in `references/core-team.md`). Collect: - **PR → Issue mapping**: Which PRs fix/close GitHub issues - **Community contributors**: Authors NOT in the core team list #### Core Team (do NOT thank as community contributors) See [core-team.md](./references/core-team.md) for the current list. ### Phase 3: Write Release Notes Use the [release notes template](./templates/release-notes-template.md) and follow these rules: #### Formatting Rules 1. **Use numbered lists** (`1.`, `2.`, `3.`) within every section — matches the house style shown in [`references/example-release-notes.md`](./references/example-release-notes.md), not bullet points. 2. **Every item uses "Verbed + Impact + Scenario"** — a human must understand what changed and why it matters to them - ✅ `**Press F5 to refresh the session list.** Re-scans history on demand so sessions that appeared after launch show up without restarting. #344` - ❌ `Fixed bug #344` (no impact or scenario) - ❌ `emit connection_state:closed on UI-initiated pane/tab close` (developer jargon) 3. **Every item ends with its PR number(s)** — a space then `#PR` after the trailing period (e.g. `… without restarting. #344` or `… in strict-mode shells. #340`). - Use the **PR number** as the primary reference (the shipped notes are PR-centric). - In the 💜 Community section you may add the linked issue too, e.g. `(#366, closes #351)`. - Group related items that share user impact into one entry with multiple numbers (e.g. `#305, #365`). 4. **Open with a metadata blockquote header**, as shown in [`references/example-release-notes.md`](./references/example-release-notes.md): the base release tag + commit + build, the head `main` commit, the new-PR count, the CI-injects-build-number note, and the "base is the tag, not `stable`" note. 5. **Frame the notes** with a one-paragraph plain-language intro (the release's headline theme) after the header, and a closing call-to-action inviting users to file issues. 6. **Omit purely internal changes** — CI fixes, code refactors, dev docs, test-only changes, localization bot updates — unless they have direct user-visible impact. (Prior releases sometimes collect these under a `## Development` section instead of omitting them; follow the maintainer's preference for the release at hand.) 7. **Avoid detailed security disclosures in public release notes** — fold security-related stability fixes into the Bug Fixes section rather than calling them out as security issues, and coordinate any security-sensitive wording with maintainers per [SECURITY.md](../../../SECURITY.md) 8. **Thank community contributors** in a 💜 Community section with GitHub profile links: ```markdown 1. [@username](https://github.com/username) (Display Name) — what they contributed. (#PR, closes #issue) ``` #### Section Structure Open with the metadata blockquote header and the intro paragraph, then use these sections in order: - `## ✨ New Features` — new capabilities users can use - `## 🔧 Improvements` — enhancements to existing features - `## 🐛 Bug Fixes` — things that were broken and are now fixed - `## 💜 Community` — external contributor thanks - `## 🚀 Top 5 Elevator-Pitch Points` — the most compelling highlights for social media / announcements Close with the call-to-action paragraph. ### Phase 4: Output 1. **Draft** into `Generated Files/release-notes-vX.Y.Z.md` — this folder is gitignored, so the working draft stays untracked while you iterate and get user sign-off. 2. Present the full notes to the user for review. 3. Also list the top 5 elevator-pitch points separately. 4. **Publish (only once approved).** Copy the finalized notes to `doc/release-notes/vX.Y.Z.md` and commit them (create the `doc/release-notes/` folder if it doesn't exist yet — this is the intended home for published release notes). Follow the format in [`references/example-release-notes.md`](./references/example-release-notes.md). This committed file is the source of truth for the version — do **not** commit the `Generated Files/` draft. ## Gotchas - **Avoid a dedicated 🔒 Security section** — prefer folding security-related stability improvements into Bug Fixes rather than publicly detailing security issues; see [SECURITY.md](../../../SECURITY.md) for vulnerability handling and coordinate sensitive wording with maintainers. - **Upstream Windows Terminal PRs** (#20xxx numbers) should be looked up on `microsoft/terminal`, not `microsoft/intelligent-terminal`. - **The "Verbed + Impact + Scenario" format is non-negotiable** — every single bullet must follow it. "Fixed X" alone is not enough; you must explain the user impact. - **Some commits are cherry-picks from upstream** — check both repos when looking up PRs. - **Group related commits** — if 3 PRs all improve the FRE, combine into one bullet with multiple issue numbers rather than 3 separate bullets. ## References - [Core team list](./references/core-team.md) - [Release notes template](./templates/release-notes-template.md) - [Previous release notes example](./references/example-release-notes.md)