release-notes

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.

   git tag --list 'v*' --merged main --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1
   

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

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

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.

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: 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

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