release-notes

# .NET Release Notes Generate and maintain release notes for .NET preview, RC, and GA releases. This skill is the **editorial writing stage** of the pipeline. It turns a scored `features.json` file into the markdown that ships in this repository. ## How it works 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-validation` / `dotnet-inspect` verifies public APIs and confirms suspect features still exist in the shipped build; review the [incremental API diff](references/api-verification.md#review-incremental-api-diffs-for-preview-upgrades) for preview-to-preview migration signals 5. `release-notes` writes curated component markdown using the higher-value entries from `features.json`. The base branch preallocates unlinked component entries in `README.md`; each component branch links its own entry when it adds the matching file. See [`format-template.md`](references/format-template.md). 6. `validate-code-samples` builds and runs the documented claims against the milestone build, catching what static API verification cannot see 7. `review-release-notes` runs a final multi-model editorial QA pass against the scoring rubric and examples 8. 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 and its index link. Each component PR targets the base branch so component teams review their own notes and matching index entry. See [`pr-layout.md`](references/pr-layout.md) for the full layout and naming scheme. Before drafting or delegating component files, confirm that the milestone's `features.json` contains the real `changes[]` and `commits{}` from `changes.json`, with matching change IDs and commit keys and scored candidates for noteworthy changes. Do not substitute a schema stub or defer feature selection to the component PRs. Give component writers the relevant candidate entries with their scores and reasons rather than a slim list of titles and labels. Before finalizing the milestone, run `review-release-notes` against the `changes.json`, `features.json`, and completed component drafts on their branches (or the base branch after they merge). Resolve noteworthy omissions it finds or record the editorial reason in `features.json`. ## Local testing (no PRs) To dry-run the skill against a milestone, only create the branch set locally. Don't push the branches or create the PRs. ## Existing-branch reruns When the milestone branch set already exists and contains drafted markdown, invoke [`update-existing-branch`](../update-existing-branch/SKILL.md). That shared skill is the canonical playbook for refreshing `changes.json`, merging the delta into `features.json`, integrating new material into existing sections, and handling review comments without clobbering human edits. ## Reference documents - [quality-bar.md](references/quality-bar.md) — what good release notes look like - [vmr-structure.md](references/vmr-structure.md) — VMR branches, tags, source-manifest.json - [pr-layout.md](references/pr-layout.md) — base + per-component branch layout - [../update-existing-branch/SKILL.md](../update-existing-branch/SKILL.md) — how to refresh a populated milestone branch set incrementally - [changes-schema.md](references/changes-schema.md) — the shared `changes.json` / `features.json` schema - [../editorial-scoring/SKILL.md](../editorial-scoring/SKILL.md) — the reusable scoring rubric and cut guidance - [feature-scoring.md](references/feature-scoring.md) — how to score and cut features - [component-mapping.md](references/component-mapping.md) — components, product slugs, output files - [format-template.md](references/format-template.md) — markdown document structure - [editorial-rules.md](references/editorial-rules.md) — tone, attribution, naming - [api-verification.md](references/api-verification.md) — using dotnet-inspect to verify APIs - [../validate-code-samples/SKILL.md](../validate-code-samples/SKILL.md) — building and running the documented claims against the milestone build - [examples/](references/examples/) — curated examples from previous releases, organized by component. **Read the examples for your component before writing.** The [examples/README.md](references/examples/README.md) lists 12 editorial principles derived from what works and what doesn't in past release notes.