| name | breaking-change-doc |
| description | Generate breaking change documentation for merged dotnet/runtime PRs. USE FOR: creating breaking change docs, "document this breaking change", "write breaking change issue for PR #NNNNN", processing PRs labeled needs-breaking-change-doc-created. DO NOT USE FOR: general code review (use code-review skill), bug fixes, API proposals (use api-proposal skill).
|
Breaking Change Documentation Skill
Generate high-quality breaking change documentation for merged dotnet/runtime
pull requests and file it as an issue in dotnet/docs.
Overview
When a PR in dotnet/runtime introduces a breaking change, the docs team needs
a structured issue in dotnet/docs describing the change, its impact, and
migration guidance. This skill automates that process:
- Gather PR context — read the PR, its diff, related issues, comments, and reviews.
- Detect version — run the helper script to determine which .NET release the change lands in.
- Check for duplicates — search dotnet/docs for existing breaking-change issues for this PR.
- Fetch reference material — read the issue template and recent example issues from dotnet/docs.
- Author the documentation — produce the issue body following the template structure and example quality.
- Publish — write output files and optionally comment on the source PR.
Trigger modes
- Interactive: Ask Copilot (e.g. "Document the breaking change
in PR #114929"). The skill presents a draft for review before publishing.
- Automated: The GitHub Agentic Workflow
at
.github/workflows/breaking-change-doc.md triggers when a PR labeled
needs-breaking-change-doc-created is merged (or the label is added to an
already-merged PR). It can also be run manually via workflow_dispatch with
an optional suppress_output flag for dry-run inspection. The compiled
workflow (.lock.yml) must be regenerated with gh aw compile after changes.
Files
| File | Purpose |
|---|
.github/workflows/breaking-change-doc.md | gh-aw workflow — triggers on PR merge/label |
.github/workflows/breaking-change-doc.lock.yml | Compiled workflow (generated by gh aw compile) |
.github/skills/breaking-change-doc/SKILL.md | This skill |
.github/skills/breaking-change-doc/Get-VersionInfo.ps1 | gh CLI-based .NET version detection |
.github/skills/breaking-change-doc/Build-IssueComment.ps1 | Builds PR comment with URL-encoded issue creation link |
Step 0: Accept Input
The user provides one of:
- A PR number (e.g.
#114929 or 114929)
- A PR URL (e.g.
https://github.com/dotnet/runtime/pull/114929)
- A request like "document the breaking change in PR 114929"
Extract the PR number. The source repository is always dotnet/runtime.
Step 1: Gather PR Context
Use GitHub tools to read comprehensive PR data. Collect all of the following:
- PR metadata: title, author, assignees, base branch, merge commit SHA, merged-at date, labels, state.
- PR body: the full description.
- Changed files: list of file paths modified.
- PR comments and reviews: read all comments and review comments for context about the change's impact.
- Closing issues: if the PR closes any issues, read those issues fully (body + comments) — they often contain the motivation and user-reported impact.
- Feature area labels: extract
area-* labels. If none exist, report an error asking the user to set one.
Identifying the feature area
Map the area-* label to the dotnet/docs feature area dropdown value:
area-* label pattern | Feature area |
|---|
area-System.Net.*, area-Networking | Networking |
area-System.Security.*, area-Cryptography | Cryptography |
area-System.Text.Json, area-Serialization | Serialization |
area-System.Xml.* | XML, XSLT |
area-Extensions-* | Extensions |
area-System.Globalization | Globalization |
area-System.Runtime.InteropServices*, area-Interop | Interop |
area-CodeGen-*, area-JIT | JIT |
area-System.Linq* | LINQ |
area-System.CodeDom, area-Analyzers | Code analysis |
area-Infrastructure-*, area-SDK | SDK |
area-System.Windows.Forms* | Windows Forms |
area-WPF | Windows Presentation Foundation (WPF) |
Most other area-System.* labels | Core .NET libraries |
If the mapping is unclear, use "Other (please put exact area in description textbox)" and
include the actual area label in the description.
Step 2: Detect Version Information
Run the helper script to determine the .NET version context:
pwsh .github/skills/breaking-change-doc/Get-VersionInfo.ps1 -PrNumber <number>
You MUST display the complete script output. The script outputs JSON that includes:
LastTagBeforeMerge — the closest release tag before the merge commitFirstTagWithChange — the first tag that contains this commit (or "Not yet released")EstimatedVersion — human-readable version string like ".NET 11 Preview 3"MergeCommit — the merge commit SHAMergedAt — when the PR was mergedBaseRef — the PR base branch used to determine version context
After running the script, print the full JSON output so it is visible in the
workflow log. Then check the JSON:
- If the JSON contains an
Error field, report the error and fall back to
reading the PR's base branch and recent tags manually to estimate the version.
- If the JSON does not contain an
Error field, use EstimatedVersion as
the version for the breaking change issue. Do not fall back to manual
detection when the script succeeds.
Step 3: Check for Existing Documentation
Search for existing breaking change issues in dotnet/docs:
- Search
dotnet/docs issues for Breaking change <PR_NUMBER> with label breaking-change.
- If a matching issue already exists, report it to the user and stop — do not create a duplicate.
Step 4: Fetch Reference Material
Issue template
Read the breaking change issue template from dotnet/docs at:
.github/ISSUE_TEMPLATE/02-breaking-change.yml
gh api repos/dotnet/docs/contents/.github/ISSUE_TEMPLATE/02-breaking-change.yml -H "Accept: application/vnd.github.raw"
This template defines the required sections and dropdown values. Use it as a
structural reference only — do not output YAML.
Example issues
Search dotnet/docs for 2-3 recent issues with the breaking-change label.
Read their bodies to understand the expected quality, tone, and level of detail.
Step 5: Author the Documentation
Generate a complete breaking change issue. The output must be clean markdown
formatted to work with the GitHub issue form template. Structure it as follows:
Required sections
Title
[Breaking change]: <concise description of the change>
Do not just repeat the PR title. Write a clear, user-facing summary.
Description
Brief description of the breaking change. Include the PR link.
Version
Use the EstimatedVersion from Step 2. Must match one of the template dropdown values
(e.g., ".NET 11 Preview 3"). If it doesn't match exactly, use
"Other (please put exact version in description textbox)" and state the version in the description.
Previous behavior
Describe what happened before the change. Include a code example if applicable
showing the old behavior.
New behavior
Describe what happens now. Include a code example if applicable showing the
new behavior. Highlight exceptions thrown, changed return values, or different
default settings.
Type of breaking change
Categorize as one or more of:
- Binary incompatible: existing binaries may fail to load/execute
- Source incompatible: existing source may fail to compile
- Behavioral change: existing binaries behave differently at runtime
Most changes are behavioral. Only mark binary/source incompatible when the
change actually affects compilation or binary loading.
Reason for change
Explain why the change was made. Reference the motivation from the PR body
and closing issues.
Recommended action
Provide specific, actionable guidance:
- Code changes the user should make
- Configuration switches to restore old behavior (if any exist, e.g. AppContext switches)
- Workarounds
Feature area
Use the mapping from Step 1.
Affected APIs
List all affected APIs. For methods, specify whether it's all overloads or
specific ones. Use fully qualified names (e.g., System.IO.Compression.ZipArchiveEntry.Open()).
Quality guidelines
- Professional tone — this is official Microsoft documentation.
- Concrete examples — before/after code snippets make the change tangible.
- Actionable guidance — don't just describe the problem, help users fix it.
- Accurate version — use the detected version from Step 2.
- Complete API list — review the diff to find all affected public APIs.
Step 6: Publish
Write the issue draft file
Create the output directory and write the full markdown content from Step 5
(everything except the title line) to
artifacts/docs/breakingChanges/issue-draft.md. This file is the primary
output and can be reviewed before taking any further action.
mkdir -p artifacts/docs/breakingChanges
Build the PR comment file
Run the helper script to produce a PR comment with a URL-encoded issue link.
Pass the PR assignees so they are @-mentioned in the comment and receive a
GitHub notification:
pwsh .github/skills/breaking-change-doc/Build-IssueComment.ps1 \
-IssueDraftPath artifacts/docs/breakingChanges/issue-draft.md \
-Title "<the [Breaking change]: ... title from Step 5>" \
-Assignees "@user1 @user2" \
-OutputPath artifacts/docs/breakingChanges/pr-comment.md
Build the -Assignees value from the PR's assignee list (from Step 1 metadata),
prefixing each GitHub username with @ and separating with spaces.
The script:
- URL-encodes the title, body, and labels using
[Uri]::EscapeDataString
- Builds a clickable
https://github.com/dotnet/docs/issues/new?... link
- Writes a brief
pr-comment.md with instructions, the link, an email
reminder, and /cc mentions of the assignees
- Warns if the URL exceeds browser length limits
The comment intentionally does not duplicate the full issue draft. The draft
is available in the issue-draft.md workflow artifact and is pre-filled in the
issue creation link.
Post the comment
When running interactively (not in dry-run mode), post the contents of
artifacts/docs/breakingChanges/pr-comment.md as a comment on the original
dotnet/runtime PR using GitHub tools.
When running in automated (gh-aw) mode, use the add_comment safe-output tool to post the comment.
When in dry-run mode or when the user has not explicitly asked to comment,
skip posting — the two files under artifacts/docs/breakingChanges/ are the
outputs for review.
AI-generated content disclosure
The Build-IssueComment.ps1 script includes the standard AI disclosure note
in the generated comment. No additional action is needed.
Email reminder
The generated comment includes an email reminder. When running interactively,
also remind the user:
Please email a link to this breaking change issue to
.NET Breaking Change Notifications.
Draft-only mode
If the user asks for a draft or review before publishing, or if you are uncertain
about any aspect of the documentation:
- Present the full issue content in chat for review.
- Ask the user to confirm before creating the issue.
- Only publish after explicit confirmation.
When the user has not explicitly asked to create the issue, default to draft mode.
Processing multiple PRs
If the user provides a GitHub search query or asks to process multiple PRs:
- Search for matching PRs using the query.
- For each PR, run Steps 1-5.
- Present a summary table of all PRs with their status (already documented vs needs docs).
- For PRs needing docs, present drafts and ask for confirmation before creating issues.
Troubleshooting
| Problem | Solution |
|---|
No area-* label on PR | Ask the user to add one, or ask which area applies |
| Version detection script fails | Read the PR's base branch and use git describe --tags --abbrev=0 manually |
| PR not yet merged | Breaking change docs are for merged PRs only — inform the user |
| Existing docs issue found | Report the existing issue URL and stop |
| Cannot determine affected APIs | Review the diff carefully; list the public types/methods in changed files |
| Workflow not triggering | Ensure gh aw compile was run and .lock.yml is committed |
| AI output needs review | Check technical accuracy of before/after behavior, API list completeness, and migration guidance |
