diff --git a/.github/skills/release-notes/SKILL.md b/.github/skills/release-notes/SKILL.md index e9431a16881..8af8ca47fa7 100644 --- 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 index 3aee81934f1..6c9dfc595b9 100644 --- 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 index a311f3db816..9b37aa31739 100644 --- 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 index d4cf65d3c2e..16a177fa519 100644 --- 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 index 0e8618e6c62..0f557462b2a 100644 --- 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. ([/ #NNNNN](https://github.com///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