dotnet · danroth27 · Jul 10, 2026
diff --git a/.github/skills/release-notes/SKILL.md b/.github/skills/release-notes/SKILL.md
@@ -15,7 +15,7 @@ This skill is the **editorial writing stage** of the pipeline. It turns a scored
 1. `generate-changes` diffs `source-manifest.json` between VMR refs to produce `changes.json`
 2. `generate-features` reads `changes.json`, resolves revert/backout relationships, and emits `features.json` with optional scores using the shared `editorial-scoring` rubric
 3. `update-existing-branch` handles incremental reruns when a milestone branch already exists, merging deltas instead of restarting from scratch
-4. `api-diff` / `dotnet-inspect` verifies public APIs and confirms suspect features still exist in the shipped build
+4. `api-diff` / `dotnet-inspect` verifies public APIs, confirms suspect features still exist in the shipped build, and diffs the previous preview against the current one to capture preview API changes (see [api-verification.md](references/api-verification.md#capturing-preview-api-changes))
 5. `release-notes` writes curated markdown using the higher-value entries from `features.json`
 6. `review-release-notes` runs a final multi-model editorial QA pass against the scoring rubric and examples
 7. Output is a set of pull requests per release milestone in dotnet/core: a base PR that holds shared metadata (`changes.json`, `features.json`, `README.md`, `build-metadata.json`) and one PR per component file. Each component PR targets the base branch so component teams review and edit their file in isolation. See [`pr-layout.md`](references/pr-layout.md) for the full layout and naming scheme.

diff --git a/.github/skills/release-notes/references/api-verification.md b/.github/skills/release-notes/references/api-verification.md
@@ -102,6 +102,26 @@ Always note the package version in a markdown comment so reviewers know the veri
 
 This makes it possible to distinguish "API doesn't exist" from "verified against a stale build."
 
+## Capturing preview API changes
+
+Preview notes double as an upgrade guide, so a preview that renames, reshapes, or removes a preview API must call that out — even when the feature already shipped in an earlier preview. A single-milestone `changes.json` can miss these: a rename often looks like an ordinary PR, and `breaking_changes` isn't always set.
+
+Diff the previous preview's ref packs against the current preview's to surface every public API delta:
+
+```bash
+dnx dotnet-inspect -y -- diff \
+  --package "Microsoft.AspNetCore.App.Ref@11.0.0-preview.5..11.0.0-preview.6" \
+  --source "$FEED"
+```
+
+For each removed or renamed public type or member:
+
+1. **Search the prior previews' notes for the old name.** If it was documented, the change is a _preview API change_ — add a migration note (`OldName` is now `NewName`) to the `Preview API changes` section and don't re-document the feature.
+2. **If it shipped in the last stable release** and the change breaks code written against it, it's a _breaking change_ instead.
+3. **If it was never public or never documented**, it usually needs no note.
+
+Record the diff range you used in a markdown comment, the same way you record verification packages, so reviewers can see the coverage.
+
 ## When to verify
 
 Verify **every** API name that appears in:

diff --git a/.github/skills/release-notes/references/changes-schema.md b/.github/skills/release-notes/references/changes-schema.md
@@ -121,6 +121,8 @@ That means a change can be:
 
 In practice, a `score` around `0-4` with `breaking_changes: true` usually means **one line in a "Breaking changes" section**, not a full feature writeup.
 
+`breaking_changes: true` also covers **preview-to-preview API changes** — renames, reshapes, or removals of APIs that have not shipped in a stable release. The writing stage routes those to a separate `Preview API changes` section and reserves `Breaking changes` for version-to-version breaks of shipped-stable APIs. See [editorial-rules.md](editorial-rules.md#preview-api-changes-vs-breaking-changes).
+
 ## Revert annotations
 
 `changes.json` is the raw shipped-change manifest. During editorial triage,

diff --git a/.github/skills/release-notes/references/editorial-rules.md b/.github/skills/release-notes/references/editorial-rules.md
@@ -146,6 +146,22 @@ Examples:
 - ❌ Repeating the full explanation of what runtime-async is from P1 (already documented)
 - ❌ "More JIT optimizations landed this preview." (no specific news)
 
+## Preview API changes vs. breaking changes
+
+Preview release notes are an upgrade guide from the previous preview. When a preview API is renamed, reshaped, or removed between previews, document the change so adopters can update — even if the feature itself was already covered in an earlier preview.
+
+- **Use a dedicated `Preview API changes` section** — list these as short migration notes (`OldName` is now `NewName`), not as new feature writeups. Don't re-document the feature; just record what changed.
+- **Reserve `Breaking changes` for version-to-version breaks** — a preview-to-preview rename is not a breaking change, because the API has not shipped in a stable release yet. Only put changes that break code written against a shipped-stable API (for example, a .NET 10 → .NET 11 behavior change) under `Breaking changes`.
+- **New default behavior is a feature, not a breaking change** — when a preview turns on new functionality by default (for example, automatic CSRF protection), document it as a feature and note the new default inside that feature's section.
+- **Check earlier previews before writing** — when an API changed, look at the prior previews' notes for the original name. If it was documented before under a different name, frame the entry as a rename that points back to that earlier coverage. This catches renames a single-milestone diff would otherwise miss (for example, `EnvironmentBoundary`, documented in Preview 1, became `EnvironmentView` in Preview 6).
+
+Examples:
+
+- ✅ "`EnvironmentBoundary` was renamed to `EnvironmentView`." (preview → preview rename, in `Preview API changes`)
+- ✅ "Cross-origin requests are now rejected by default." (new default behavior, documented as a feature)
+- ❌ Listing a preview-only rename under `Breaking changes`
+- ❌ Re-documenting the whole `EnvironmentView` feature when only the name changed
+
 ## Filtered features
 
 When you cut a feature for failing the 20/80 rule or two-sentence test, record it in an HTML comment block in the output file. This creates a learning record — future runs and human reviewers can see what was considered and why it was excluded.

diff --git a/.github/skills/release-notes/references/format-template.md b/.github/skills/release-notes/references/format-template.md
@@ -18,9 +18,13 @@ Standard document structure for .NET release notes markdown files.
 
 <description> ([<owner>/<repo> #NNNNN](https://github.com/<owner>/<repo>/pull/NNNNN)).
 
+## Preview API changes
+
+- Migration note for a preview API that changed since the previous preview (`OldName` is now `NewName`) — preview only, not a version-to-version break
+
 ## Breaking changes
 
-- Short migration note or heads-up for narrower changes that users may need to react to
+- Short migration note or heads-up for a version-to-version break of an API that shipped in a stable release
 
 ## Bug fixes
 
@@ -87,7 +91,7 @@ Known component docs links:
 2. **One paragraph of context** — what the feature does and why it matters in concrete terms, with PR/issue links; avoid inferred feelings or marketing-style claims
 3. **Code sample** — show the feature in use
 4. **Feature ordering** — highest customer impact first
-5. **Breaking changes near the end** — low-score entries with `breaking_changes: true` usually belong in a short section before Bug fixes, not as full feature sections
+5. **Breaking changes vs. Preview API changes** — put version-to-version breaks of shipped-stable APIs in a short `Breaking changes` section before Bug fixes. Put preview-to-preview API changes (renames, reshapes, or removals of APIs that have not shipped stable) in a separate `Preview API changes` section, framed as migration notes (`OldName` is now `NewName`). Both hold low-score `breaking_changes: true` entries, not full feature sections; omit either section when it would be empty. See [editorial-rules.md](editorial-rules.md#preview-api-changes-vs-breaking-changes).
 6. **Preview feature callout** — when a feature is listed in `release-notes/features.json`, start its section with the standard blockquote callout from that file
 
 ## Issue and PR references