Encode .NET 11 Preview 7 retrospective into the release-notes skills by danroth27 · Pull Request #10516 · dotnet/core

danroth27 · 2026-08-02T22:06:16Z

Folds the lessons from generating and validating the .NET 11 Preview 7 release notes back into the release-notes skills, so future milestones apply the same provenance, runtime-verification, editorial, and PR-management checks.

What prompted this

Four documented claims in the Preview 7 ASP.NET Core notes were wrong, and none were catchable by static managed API verification alone:

Claim	Reality	Why static API verification missed it
`Blazor.pause.waitFor(fn)`	Does not exist	JavaScript surface area is invisible to a managed API check
`.RequireAntiforgeryToken()`	Does not exist	There was no symbol to verify
`EnableClientValidation`	The shipped API is `DisableClientValidation`, with inverted polarity	A name-only check doesn't verify defaults or meaning
A documented sample	Compiled but returned HTTP 500	`[PersistentState]` silently required a public property

The errors were found by building and running maintained samples against the actual milestone build.

Changes

Runtime verification

Adds the new validate-code-samples skill, filling the runtime-verification stage that api-diff-validation already referenced.
Documents selecting the milestone's matching SDK feature-band or preview build through the latest-builds table linked from dotnet/sdk, confirming VMR provenance with productCommit-*.json and build-metadata.json, and installing it in a scoped location instead of relying on a machine-wide preview SDK.
Requires compiling every sample and exercising documented defaults, polarity, JavaScript/browser APIs, endpoints, runtime behavior, and public feature reachability.
Adds guidance for recording evidence and deciding whether to fix the notes, update a stale sample, or drop an unsupported claim.
Wires validate-code-samples into the main release-notes workflow and fixes the link from api-diff-validation.

Shipped-change and milestone provenance

Adds a milestone cross-check to generate-changes for repositories that maintain per-preview milestones: dotnet/sdk, dotnet/aspnetcore, dotnet/runtime, and dotnet/efcore.
Keeps changes.json as the authoritative shipped-change manifest. Milestones are strong but not conclusive supporting evidence: they are normally applied by automation, but assignments can be changed, incorrect, stale, or followed by a revert.
Requires independent verification before adding anything discovered through a milestone sweep and distinguishes repositories that don't maintain per-preview milestones from repositories with no shipped changes.
Adds the corresponding provenance rule to API verification: proving that an API exists in the current build does not prove that it changed in this milestone. Features discovered while testing must be traced back to the current milestone before being documented.
Calls out the limits of static verification for JavaScript APIs, defaults and polarity, and runtime-only behavior.

Editorial structure

Defines the Breaking changes section in preview notes as the upgrade guidance from the previous preview, covering renamed APIs, new analyzer diagnostics, changed defaults, and other changes that would otherwise cause build errors, warnings, or silent behavior changes.
Keeps removed workarounds with the corresponding bug fix rather than misclassifying them as breaking changes.
Updates the Bug fixes format to group fixes by namespace or feature area, exactly one level deep.
Requires one PR-linked bullet per fix, using a cleaned-up PR or issue title as the link text, with no bundled links or trailing citation/prose. Test-only, CI, and infrastructure fixes remain excluded.

PR creation, ownership, and merge flow

Documents pushing the milestone base branch before opening component PRs and checking that each component branch is based directly on the base commit, avoiding missing base branches and noisy component diffs.
Requires validating owner mappings through the repository assignees endpoint and re-reading each created PR because GitHub can silently drop non-assignable users.
Documents that gh pr edit is unusable in dotnet/core because of the Projects (classic) GraphQL failure, including title/body edits as well as assignee changes, and provides REST alternatives.
Makes component owners responsible for merging their approved PR into the milestone base branch and requires that responsibility to be stated when owners are notified.

Notes

Supersedes the release-notes/pr-owner-merges branch, whose commit is included here; that branch can be deleted.
.github/CODEOWNERS separately lists /release-notes/ @rbhanda @leecow @victorisr. That is review ownership rather than per-component ownership, so it is deliberately unchanged.

Reviewing and approving a component release notes PR is not enough - the owner is responsible for merging it into the milestone base branch once it's ready, rather than leaving it for someone else. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: a851ab96-8780-407d-97d0-50eed422ead5

Add a validate-code-samples skill and fold the lessons from generating the Preview 7 notes back into the surrounding skills. - Add .github/skills/validate-code-samples/SKILL.md, the runtime-verification stage that api-diff-validation already referenced but that did not exist. Covers acquiring the milestone build from ci.dot.net (build-metadata.json already emits sdk_url), pinning provenance via productCommit, installing scoped rather than machine-wide, and building/running every documented claim. Static API checks cannot see JS surface area, cannot catch inverted polarity, and cannot catch runtime-only requirements. - generate-changes: add a milestone cross-check with measured per-repo coverage. Only aspnetcore, runtime, sdk, and (weakly) efcore populate preview milestones reliably; roslyn and razor have no 11.x milestones at all. The milestone supplements changes.json, never replaces it. - api-verification: add the milestone-provenance rule. A change that shipped in an earlier preview still verifies against the current build, so presence in the build does not prove it belongs in these notes. - format-template: add the "Upgrading from the previous preview" section so preview-to-preview breaking changes are documented. - pr-layout: document creating the base branch first (branch globs exclude it), verifying assignees actually stuck, and the gh pr edit REST workaround. - component-mapping: add an owner-freshness check using the assignees endpoint. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: a851ab96-8780-407d-97d0-50eed422ead5

- generate-changes: replace the P7-specific coverage table with a plain list of the repos that maintain preview milestones, and add a rule that anything found via a milestone sweep must be verified independently. Milestone membership is a hand-applied label, so it shows intent, not that the change shipped. - api-verification: say "a PR associated with this milestone" rather than "a PR in this milestone", which read as GitHub milestone membership even though not every repo uses milestones per preview. - format-template: fold the preview upgrade guidance into the Breaking changes section. Preview notes already scope that section to what changed in the milestone, so it is the preview-to-preview upgrade story. Workaround removal stays called out separately since it is not a breaking change. - component-mapping, validate-code-samples: drop the historical anecdotes and keep the rules. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: a851ab96-8780-407d-97d0-50eed422ead5

Milestones are applied by automation, so they are usually correct. They can be changed or applied incorrectly by hand afterwards, but that is the exception. The previous wording described them as hand-applied, which overstated the unreliability and framed verification as expecting a problem rather than confirming the expected result. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: a851ab96-8780-407d-97d0-50eed422ead5

The Projects (classic) GraphQL failure is not specific to the assignee flags - gh pr edit --body-file fails against dotnet/core the same way and silently leaves the body unchanged. Note the REST PATCH for title and body edits too. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: a851ab96-8780-407d-97d0-50eed422ead5

Each bug fix is one bullet: a single markdown link pointing at the PR, with a cleaned-up version of the PR or issue title as the display text. No area sub-grouping, no bundling several PRs into one bullet, and no trailing org/repo #number citation, since the link already carries it. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: a851ab96-8780-407d-97d0-50eed422ead5

One bullet per PR with a cleaned-up title is easier to scan when the fixes are still grouped by namespace or area, so keep the grouping one level deep rather than a single flat list. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: a851ab96-8780-407d-97d0-50eed422ead5

Milestones are applied by automation and are usually correct, so describe them as strong but not conclusive evidence that a change shipped. Keep the separate changes.json and build verification step for the occasional incorrect or stale milestone assignment. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: a851ab96-8780-407d-97d0-50eed422ead5

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: a851ab96-8780-407d-97d0-50eed422ead5

Copilot AI added 2 commits August 2, 2026 14:43