vsadov/satori/breaking-change-doc

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:

1. Gather PR context — read the PR, its diff, related issues, comments, and reviews.
2. Detect version — run the helper script to determine which .NET release the change lands in.
3. Check for duplicates — search dotnet/docs for existing breaking-change issues for this PR.
4. Fetch reference material — read the issue template and recent example issues from dotnet/docs.
5. Author the documentation — produce the issue body following the template structure and example quality.
6. 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.

Files

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"

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:

1. PR metadata: title, author, assignees, base branch, merge commit SHA, merged-at date, labels, state.
2. PR body: the full description.
3. Changed files: list of file paths modified.
4. PR comments and reviews: read all comments and review comments for context about the change's impact.
5. Closing issues: if the PR closes any issues, read those issues fully (body + comments) — they often contain the motivation and user-reported impact.
6. 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:

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 determines the version from the existence of release/<major>.<minor>-preview<N> (and later -rc<N> / GA) branches: once a milestone is branched it is locked, so a change merged to main ships in the next milestone. Two things can move it into an earlier, already-branched milestone: the merge commit is already contained in that branch (compare API), or a linked PR (open or merged) targets that branch — in the latter case the version is reported as tentative, because such a linked PR is only "a PR that references this one and targets a release branch" and is not verified to be a genuine backport (and a cherry-pick backport's commit differs from this PR's, so containment can't confirm it). Backports are discovered via the primary PR's cross-reference graph (GitHub timeline), so they are found regardless of the backport's head-branch name. For predicting the next, unbranched milestone the script assumes the standard .NET cadence of 7 previews, then 2 RCs, then GA (tunable via -PreviewCount / -RcCount), so it correctly rolls over Preview 7 → RC 1 and RC 2 → GA. For changes that already shipped in a past major (whose preview/RC branches have been pruned), containment only resolves to the GA line, so the script then scans the persistent release tags to recover the exact first preview/RC. The JSON output includes:

• EstimatedVersion — human-readable version string like ".NET 11 Preview 7"
• Tentative — true when the version depends on an unverified linked release-branch

PR (open or merged)

• DetectionMethod — how the version was determined (direct release-branch merge,

own-commit containment in a branched milestone, tag-refined first-shipped version, potential linked backport, or "ships after highest branched milestone")

• FallbackVersion — present only when Tentative is true: the version to use if

the linked PR turns out not to be a genuine backport (the normal "ships after highest branched milestone" result), so you don't have to re-derive it

• HighestBranch — the highest release branch found for the target major.minor
• ContainedInBranch — present only when the merge commit is already in a branch
• FirstShippedTag — set when the version was refined from release tags (the exact

tag where the change first shipped, e.g. v9.0.0-preview.4.24266.19)

• Backports — array of potential backport PRs cross-referenced from this PR and

targeting a release branch (Number, State, Merged, Target, Title), including cross-major servicing backports (informational; they do not change the primary version)

• MergeCommit — the merge commit SHA
• MergedAt — when the PR was merged
• BaseRef — the PR base branch used to determine version context

The `Backports` entries are candidates, not confirmed backports. A cross-reference only means the PR mentions this one; it does not prove it is a backport of this change. When a backport is relevant to the outcome (especially a tentative version, or when listing backports in the draft), confirm it is a genuine backport by inspecting the candidate PR's title, description, and — if still unclear — its code diff, before relying on it.

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

inspecting the release branches manually (gh api repos/dotnet/runtime/branches) to estimate the version.

• If Tentative is true, confirm the referenced linked PR is a genuine backport of

this change (title/description/diff). If it is, use EstimatedVersion and note in the draft that it depends on that backport; if it is not, use FallbackVersion instead.

• If the candidate backport is confirmed and merged, treat the EstimatedVersion as definitive.

If it's confirmed and still open, treat the EstimatedVersion as provisional and note this in the draft.

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

Also capture the template's `labels:` and `assignees:` values — these are the authoritative source for the labels and assignee applied to the new issue and must be passed to Build-IssueComment.ps1 in Step 6.

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