microsoft--powertoys/.github/skills/release-note-generation/references/step1-collection.md

Step 1: Collection and Milestones

1.0 To-do

• 1.0.0 Verify GitHub CLI authentication (REQUIRED)
• 1.0.1 Generate MemberList.md (REQUIRED)
• 1.1 Collect PRs
• 1.2 Assign Milestones (REQUIRED)

Required Variables

⚠️ Before starting, confirm these values with the user:

Variable	Description	Example
{{ReleaseVersion}}	Target release version	0.97
{{PreviousReleaseTag}}	Previous release tag from releases page	v0.96.1

If user hasn't specified {{ReleaseVersion}}, ASK: "What release version are we generating notes for? (e.g., 0.97)"

{{PreviousReleaseTag}} is derived from the releases page, not user input. Use the latest published release tag (top of the page). You will use its tag name and tag commit SHA in Step 1.

---

1.0.0 Verify GitHub CLI Authentication (REQUIRED)

⚠️ BLOCKING: The collection script requires an authenticated gh CLI to fetch PR metadata and co-author information via GitHub's GraphQL API. Without authentication, PR data and NeedThanks attribution will be incomplete.

Check authentication status

gh auth status

If authenticated: You'll see Logged in to github.com account <username>. Proceed to 1.0.1.

If NOT authenticated: Run the login flow before continuing:

# Interactive login (opens browser for OAuth)
gh auth login --hostname github.com --web

# Or use a personal access token
gh auth login --with-token <<< "YOUR_GITHUB_TOKEN"

Required scopes: repo (for reading PR data and assigning milestones)

After login, verify again with gh auth status and confirm exit code 0.

---

1.0.1 Generate MemberList.md (REQUIRED)

Create Generated Files/ReleaseNotes/MemberList.md from the PowerToys core team section in COMMUNITY.md.

Rules:

• One GitHub username per line, no @ prefix.
• Use the usernames exactly as listed in the core team section.
• Do not include former team members or other sections.

Example (format only):

example-user
another-user

---

1.1 Collect PRs

1.1.1 Get the previous release commit

1. Open the PowerToys releases page
2. Find the latest release (e.g., v0.96.1, which should be at the top)
3. Set {{PreviousReleaseTag}} to that tag name (e.g., v0.96.1)
4. Copy the full tag commit SHA as {{SHALastRelease}}

If the release SHA is not in your branch history: Use the helper script to find an equivalent commit on the target branch by matching the commit title:

pwsh ./.github/skills/release-note-generation/scripts/find-commit-by-title.ps1 `
    -Commit '{{SHALastRelease}}' `
    -Branch 'stable'

1.1.2 Run collection script against stable branch

# Collect PRs from previous release to current HEAD of stable branch
pwsh ./.github/skills/release-note-generation/scripts/dump-prs-since-commit.ps1 `
    -StartCommit '{{SHALastRelease}}' `
    -Branch 'stable' `
    -OutputDir 'Generated Files/ReleaseNotes'

Parameters:

• -StartCommit - Previous release tag or commit SHA (exclusive)
• -Branch - Always use stable branch, not main (script uses origin/stable as the end ref)
• -EndCommit - Optional override if you need a custom end ref
• -OutputDir - Output directory for generated files

Reliability check: If the script reports “No commits found”, the stable branch has not moved since the last release. In that case, either:

• Confirm this is expected and stop (no new release notes), or
• Re-run against main to gather pending changes for the next release cycle.

The script detects both merge commits (Merge pull request #12345) and squash commits (Feature (#12345)).

Output (in Generated Files/ReleaseNotes/):

• milestone_prs.json - raw PR data
• sorted_prs.csv - sorted PR list with columns: Id, Title, Labels, Author, Url, Body, CopilotSummary, NeedThanks
  • Author: Comma-separated list of all contributors (PR opener + co-authors from commit trailers)
  • NeedThanks: Comma-separated list of external contributors to thank (excludes core team members from MemberList.md). Empty string means no thanks needed.

---

1.2 Assign Milestones (REQUIRED)

Before generating release notes, ensure all collected PRs have the correct milestone assigned.

⚠️ CRITICAL: Do NOT proceed to labeling until all PRs have milestones assigned.

1.2.1 Check current milestone status (dry run)

# Dry run first to see what would be changed:
pwsh ./.github/skills/release-note-generation/scripts/collect-or-apply-milestones.ps1 `
    -InputCsv 'Generated Files/ReleaseNotes/sorted_prs.csv' `
    -OutputCsv 'Generated Files/ReleaseNotes/prs_with_milestone.csv' `
    -DefaultMilestone 'PowerToys {{ReleaseVersion}}' `
    -ApplyMissing -WhatIf

This queries GitHub for each PR's current milestone and shows which PRs would be updated.

1.2.2 Apply milestones to PRs missing them

# Apply for real:
pwsh ./.github/skills/release-note-generation/scripts/collect-or-apply-milestones.ps1 `
    -InputCsv 'Generated Files/ReleaseNotes/sorted_prs.csv' `
    -OutputCsv 'Generated Files/ReleaseNotes/prs_with_milestone.csv' `
    -DefaultMilestone 'PowerToys {{ReleaseVersion}}' `
    -ApplyMissing

Script Behavior:

• Queries each PR's current milestone from GitHub
• PRs that already have a milestone are skipped (not overwritten)
• PRs missing a milestone get the default milestone applied
• Outputs prs_with_milestone.csv with (Id, Milestone) columns
• Produces summary: Updated=X Skipped=Y Failed=Z

Validation: After assignment, all PRs in prs_with_milestone.csv should have the target milestone.

---

Additional Commands

Collect milestones only (no changes to GitHub)

pwsh ./.github/skills/release-note-generation/scripts/collect-or-apply-milestones.ps1 `
    -InputCsv 'Generated Files/ReleaseNotes/sorted_prs.csv' `
    -OutputCsv 'Generated Files/ReleaseNotes/prs_with_milestone.csv'

Local assignment only (fill blanks in CSV, no GitHub changes)

pwsh ./.github/skills/release-note-generation/scripts/collect-or-apply-milestones.ps1 `
    -InputCsv 'Generated Files/ReleaseNotes/sorted_prs.csv' `
    -OutputCsv 'Generated Files/ReleaseNotes/prs_with_milestone.csv' `
    -DefaultMilestone 'PowerToys {{ReleaseVersion}}' `
    -LocalAssign