version: "1.0.0"

name: release-notes description: 'Generate user-facing release notes for Intelligent Terminal. Use when asked to write release notes, changelog, what-is-new summary, or prepare a release. Compares git commits between releases, looks up PR-linked issues and community contributors, then outputs formatted notes with "Verbed + Impact + Scenario" style bullets, issue references, and contributor thanks.'

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.)

1. 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 ``

1. 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):

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` 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 for the current list.

Phase 3: Write Release Notes

Use the release notes template 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`, not bullet points.

1. 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)

1. 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).

1. Open with a metadata blockquote header, as shown in `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.

1. 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.

1. 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.)

1. 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

1. Thank community contributors in a 💜 Community section with GitHub profile links:

```markdown

1. @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`. 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 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
• Release notes template
• Previous release notes example