breaking-change-doc

---
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](https://github.com/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 prepares a docs issue draft and posts the
  documentation comment on the source PR without another approval step,
  unless the user requests draft-only, dry-run, or review before publication,
  or unresolved uncertainty about the documentation requires review.
  Creating the docs issue is a separate publication decision.
- **Automated**: The [GitHub Agentic Workflow](https://github.github.com/gh-aw/)
  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

| 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` | Release-branch/tag-based .NET version detection (via `gh` CLI) |
| `.github/skills/breaking-change-doc/Build-IssueComment.ps1` | Builds PR comment with a hybrid pre-filled 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"

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:

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

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

### Build the PR comment file

Run the helper script to produce a PR comment with a pre-filled issue link.
Pass the labels and assignee **from the docs issue template** (Step 4) for the new
issue, and pass the runtime PR's assignees separately so they are `@`-mentioned:

```bash
pwsh .github/skills/breaking-change-doc/Build-IssueComment.ps1 \
  -IssueDraftPath artifacts/docs/breakingChanges/issue-draft.md \
  -Title "<the [Breaking change]: ... title from Step 5>" \
  -Labels "<comma-separated labels from the template's labels: field>" \
  -IssueAssignees "<comma-separated usernames from the template's assignees: field>" \
  -CcMentions "@user1 @user2" \
  -OutputPath artifacts/docs/breakingChanges/pr-comment.md
```

- `-Labels` and `-IssueAssignees` come from the dotnet/docs template captured in
  Step 4 (e.g. `-Labels "breaking-change"`, `-IssueAssignees "gewarren"`).
- `-CcMentions` is built from the **runtime PR's** assignee list (Step 1 metadata),
  prefixing each GitHub username with `@` and separating with spaces. These are
  used for the `/cc` notification line.

The script:
- Builds a clickable `https://github.com/dotnet/docs/issues/new?...` link that opens
  a **blank markdown editor** (not the structured form) with the title, labels, and
  assignee pre-filled.
- Uses a **hybrid** body strategy: if the full URL (including the URL-encoded body)
  stays within a conservative ~8000-byte budget, the body is pre-filled too so the
  issue is one click away. Otherwise the body is dropped from the URL and embedded in
  the comment inside a `<details>` block for the user to copy-paste into the opened
  editor.
- Warns if the comment exceeds GitHub's 65536-character comment limit.

### Post the comment

Follow the repository's [GitHub publication authorization rules](../../copilot-instructions.md#github-publication-authorization).
A user-requested execution of this documentation workflow authorizes posting
the contents of `artifacts/docs/breakingChanges/pr-comment.md` on the specified
source dotnet/runtime PR without another approval step. This authorizes only
the generated documentation comment, not creating the docs issue or posting
unrelated comments.

Invoking this skill incidentally during another coding task does not grant
that permission. In that case, use the general publication authorization
rules: proceed with explicit advance permission in an interactive session,
or present the proposed comment and obtain approval before posting.

When actually executing a repository-configured gh-aw workflow that authorizes
this comment, use its add_comment safe-output tool within the configured scope.
Running unattended or invoking this skill alone does not grant that permission.

If the user requests draft-only, dry-run, or review before publication, or
publication is otherwise unauthorized, skip posting — the two files under
`artifacts/docs/breakingChanges/` are the outputs for review.

Unresolved uncertainty about any aspect of the documentation also holds the
source-PR comment, in both interactive and automated runs. Post it only after
the uncertainty is resolved or the user has reviewed the proposed comment,
been told what remains uncertain, and explicitly approved posting it. An
initial workflow request or advance publication permission alone does not
satisfy this content-review requirement. If confirmation cannot be obtained,
keep the comment local and report the uncertainty without posting it.

### AI-generated content disclosure

The `Build-IssueComment.ps1` script includes the standard AI disclosure note
and the email reminder to the .NET Breaking Change Notifications alias in the
generated comment. No additional action is needed.

---

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

1. Present the issue draft and proposed source-PR comment for review, explaining
   any unresolved uncertainty.
2. Obtain explicit approval before creating the docs issue or posting the
   source-PR comment. Approval of one does not authorize the other.
3. Publish only the approved artifacts. If approval cannot be obtained, keep
   the unapproved outputs local and report the pending review.

When the user has not explicitly asked to create the docs issue, keep that
issue as a draft. This alone does not suppress an authorized source-PR
documentation comment. A draft-only, dry-run, or review-before-publication
request suppresses the comment as well.

Unresolved uncertainty also holds the comment under the conditions in
[Post the comment](#post-the-comment). Once the uncertainty is resolved, an
otherwise authorized source-PR comment may be posted without another approval;
creating the docs issue remains a separate publication decision.

---

## Processing multiple PRs

If the user provides a GitHub search query or asks to process multiple PRs:

1. Search for matching PRs using the query.
2. For each PR, run Steps 1-5.
3. Present a summary table of all PRs with their status (already documented vs needs docs).
4. For PRs needing docs, prepare drafts and apply the publication authorization
   rules above. In an interactive session, advance permission may cover the
   whole specified batch; otherwise, present each draft and obtain approval
   before creating that issue.

---

## Troubleshooting

| Problem | Solution |
|---|---|
| No `area-*` label on PR | Ask the user to add one, or ask which area applies |
| Version detection script fails | Inspect release branches manually: `gh api repos/dotnet/runtime/branches --paginate --jq '.[].name'` and find the highest milestone branch (`release/<M>.<m>-preview<N>`, `release/<M>.<m>-rc<N>`, or `release/<M>.<m>`); a change on `main` ships in the **next** milestone (Preview N+1, or RC 1 after the final Preview, or GA after the final RC) |
| 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 |

More agent context in dotnet/runtime

23 other files this repository gives its agents.