release-note-generation

name release-note-generation description Toolkit for generating PowerToys stable or preview release notes from GitHub milestones, commit ranges, or Azure DevOps release-candidate builds. Use when asked to create release notes, summarize milestone PRs, generate changelog, prepare a draft preview release, calculate PR deltas across main and stable, update release documentation, manage PR milestones, or prepare and validate release assets. license Complete terms in LICENSE.txt Release Note Generation Skill Generate professional PowerToys release notes by collecting merged PRs, summarizing each PR with the local CLI agent, grouping by label, and producing user-facing summaries. Stable and preview releases share the same PR metadata, attribution, grouping, and formatting rules. Output Directory All generated artifacts are placed under Generated Files/ReleaseNotes/ at the repository root (gitignored). Generated Files/ReleaseNotes/ ├── milestone_prs.json # Raw PR data from GitHub ├── sorted_prs.csv # Sorted PR list with Copilot summaries ├── prs_with_milestone.csv # Milestone assignment tracking ├── grouped_csv/ # PRs grouped by label (one CSV per label) ├── grouped_md/ # Generated markdown summaries per label └── v{VERSION}-release-notes.md # Final consolidated release notes Preview-release runs use an isolated subdirectory: Generated Files/ReleaseNotes/preview-<buildId>/ ├── release-context.json ├── delta-commits.json ├── delta-prs.json ├── removed-prs.json ├── unattributed-commits.json ├── MemberList.md ├── milestone_prs.json ├── sorted_prs.csv ├── release-notes.md ├── hashes.md ├── release-manifest.json # Local audit artifact; never uploaded ├── assets-manifest.json # Local asset inventory; never uploaded └── final-review.md When to Use This Skill Generate release notes for a milestone Summarize PRs merged in a release Generate per-PR review summaries locally for release-notes copy Assign milestones to PRs missing them Collect PRs between two commits/tags Update README.md for a new version Prepare GitHub release assets (download installers/symbols + compute hashes) Prepare a complete draft preview release from an ADO build URL or build ID Compare preview contents across main and stable branch transitions Prerequisites GitHub CLI ( gh ) installed and authenticated — The collection script uses gh pr view and gh api graphql to fetch PR metadata and co-author information. Run gh auth status to verify; if not logged in, run gh auth login first. See Step 1.0.0 for details. MCP Server: github-mcp-server installed (used to fetch PR diffs/files for the local-agent review step) For preview releases and prepare-release-assets.ps1 : Azure CLI authenticated against the Microsoft tenant ( az login ) with the azure-devops extension; access to the microsoft/Dart ADO project Required Variables For a stable release, confirm {{ReleaseVersion}} with the user before starting. For a preview release, do not request a version: derive it from the candidate ADO build. Variable Description Example {{ReleaseVersion}} Target release version 0.98 Preview mode instead requires one ADO build URL or numeric build ID. It derives the version, source commit, branch, and previous release without asking the user. Scenario routing Read the scenario index , then follow only the selected scenario: Stable release for milestone- or version-based release notes. Preview release for an autonomous ADO-build-to-draft workflow. Workflow Overview ┌────────────────────────────────┐ │ 1.0 Verify gh auth + MemberList │ └────────────────────────────────┘ ↓ ┌────────────────────────────────┐ │ 1.1 Collect PRs (stable range) │ └────────────────────────────────┘ ↓ ┌────────────────────────────────┐ │ 1.2 Assign Milestones │ └────────────────────────────────┘ ↓ ┌────────────────────────────────┐ │ 2.1–2.4 Label PRs (auto+human) │ └────────────────────────────────┘ ↓ ┌────────────────────────────────┐ │ 3.1 Local-agent PR summaries │ │ (writes CopilotSummary) │ └────────────────────────────────┘ ↓ ┌────────────────────────────────┐ │ 3.2 (Optional) Refresh PR data │ └────────────────────────────────┘ ↓ ┌────────────────────────────────┐ │ 3.3 Group by label │ │ (grouped_csv) │ └────────────────────────────────┘ ↓ ┌────────────────────────────────┐ │ 4.1 Summarize (grouped_md) │ └────────────────────────────────┘ ↓ ┌────────────────────────────────┐ │ 4.2 Final notes (v{VERSION}.md) │ └────────────────────────────────┘ Step Action Details 1.0 Verify prerequisites gh auth status must pass; generate MemberList.md 1.1 Collect PRs From previous release tag on stable branch → sorted_prs.csv 1.2 Assign Milestones Ensure all PRs have correct milestone 2.1–2.4 Label PRs Auto-suggest + human label low-confidence 3.1–3.3 Reviews & Grouping Local agent summarizes each PR diff into CopilotSummary → (optional refresh) → group by label 4.1–4.2 Summaries & Final Generate grouped summaries, then consolidate Detailed workflow docs Do not read all steps at once—only read the step you are executing. Step 1: Collection & Milestones Step 2: Labeling PRs Step 3: Reviews & Grouping Step 4: Summarization Available Scripts Script Purpose dump-prs-since-commit.ps1 Fetch PRs between commits/tags group-prs-by-label.ps1 Group PRs into CSVs collect-or-apply-milestones.ps1 Assign milestones diff_prs.ps1 Incremental PR diff prepare-release-assets.ps1 Download installers + symbols from an ADO build, compute SHA256, emit the "Installer Hashes" markdown table for the GitHub release page get-release-build-metadata.ps1 Resolve and validate the candidate build identity, version, channel, intent, and source commit get-previous-published-release.ps1 Select the latest published stable or preview release that predates the candidate queue time get-preview-release-delta.ps1 Calculate semantic added/removed PRs between exact release commits collect-pr-metadata.ps1 Normalize GitHub metadata for an explicit set of PR numbers new-preview-release-manifest.ps1 Create the auditable build, baseline, and semantic-delta release manifest upsert-draft-preview-release.ps1 Create or update a draft prerelease without exposing a publish operation verify-draft-preview-release.ps1 Verify draft flags, target commit, managed body, and uploaded assets References Sample Output - Example summary formatting Detailed Instructions - Legacy full documentation Conventions Terminal usage : Disabled by default; only run scripts when user explicitly requests Preview automation : An explicit request to prepare a preview release, or invocation by the Prepare Preview Release agent, authorizes the canonical preview scripts Preview manifests : Keep release-manifest.json and assets-manifest.json in the local audit package; do not upload either file as a GitHub release asset Preview note layout : Place the Installer Hashes section immediately after the title and short public introduction, before Highlights and all change sections Batch generation : Generate ALL grouped_md files in one pass, then human reviews PR order : Preserve order from sorted_prs.csv in all outputs Label filtering : Keeps Product-* , Area-* , GitHub* , *Plugin , Issue-* Troubleshooting Issue Solution gh command not found Install GitHub CLI and add to PATH No PRs returned Verify milestone title matches exactly Empty CopilotSummary for many PRs Run Step 3.1 (local-agent summaries). Do not use mcp_github_request_copilot_review from a CLI/coding agent — the GitHub API rejects bot-initiated review requests, so the column will stay empty. Many unlabeled PRs Return to labeling step before grouping prepare-release-assets.ps1 fails with "Failed to acquire ADO access token" Run az login and ensure you have access to the microsoft/Dart ADO project Candidate has no release-metadata.json The metadata resolver uses pipeline-log fallback; ambiguous or conflicting values stop the run First preview after switching branches has unexpected changes Review removed-prs.json and unattributed-commits.json ; see preview delta resolution