generate-changes

# Generate `changes.json` Produce the authoritative `changes.json` input for a preview, RC, or GA release milestone. This is the **VMR-aware data acquisition stage** of the release notes pipeline: 1. Determine which milestone(s) are active 2. Resolve the correct `--base` and `--head` refs 3. Run `release-notes generate changes` 4. Write `changes.json` into the correct `release-notes/` folder ## When to use - A new preview, RC, or GA milestone needs fresh shipped-change data - The user wants to know whether **multiple preview milestones** are active at once - The release notes branch should be refreshed after the VMR moved forward - `changes.json` is missing, stale, or suspected to have the wrong ref selection ## Preview-only branch targeting This is the subtle part, and it mostly matters for **previews**. Multiple preview milestones can be active simultaneously: ```text Latest shipped in this repo: Preview 3 VMR main: Preview 5 VMR release branch exists: Preview 4 → Generate one `changes.json` for Preview 4 → Generate one `changes.json` for Preview 5 ``` For each target milestone `N`: | Milestone state | Base ref | Head ref | | --------------------------------------- | ----------- | ------------------ | | Tag exists for N | Tag for N-1 | Tag for N | | Release branch exists for N, no tag yet | Tag for N-1 | Release branch tip | | Only on `main` | Tag for N-1 | `main` | **Critical rule:** never use `main` for milestone `N` if `main` has already moved to `N+1`. ## Inputs The user should provide as much of this as they know: - **Target release** — e.g. `.NET 11 Preview 4`, `.NET 10 RC 2`, `.NET 10 GA` - **VMR clone path** — defaults to a local clone of `dotnet/dotnet` - Optionally, the exact refs if they already know them If the user does **not** specify the milestone, infer it from: 1. `release-notes/{version}/releases.json` in this repo 2. `eng/Versions.props` on `main` in the VMR 3. Matching preview tags and release branches in the VMR ## Process ### 1. Determine the floor from `releases.json` Find the latest shipped milestone in this repo. That tells you the lowest in-flight milestone that may need work. ### 2. Inspect the VMR - Read `eng/Versions.props` on `main` to determine the current prerelease iteration - List matching VMR tags for finalized milestones - List matching VMR release branches for stabilizing milestones Use the [VMR structure reference](../release-notes/references/vmr-structure.md) for naming conventions and branch patterns. ### 3. Resolve `--base` and `--head` For each active milestone: - `--base` is the previous shipped milestone tag - `--head` is the milestone tag, release branch tip, or `main`, depending on what exists ### 4. Generate the file ```bash release-notes generate changes <vmr-clone-path> \ --base <previous-release-tag> \ --head <current-release-ref> \ --version "<release-version>" \ --date "<yyyy-mm-dd>" \ --labels \ --output release-notes/<major.minor>/<milestone-path>/changes.json ``` Examples: ```bash # Preview milestone release-notes generate changes ~/git/dotnet \ --base v11.0.0-preview.3.26210.100 \ --head origin/release/11.0.1xx-preview4 \ --version "11.0.0-preview.4" \ --labels \ --output release-notes/11.0/preview/preview4/changes.json # GA/patch milestone release-notes generate changes ~/git/dotnet \ --base v10.0.7 \ --head v10.0.8 \ --version "10.0.8" \ --output release-notes/10.0/10.0.8/changes.json ``` ## Output contract The output file must follow the shared schema documented in [changes-schema.md](../release-notes/references/changes-schema.md): - top-level `release_version`, `release_date`, `changes`, `commits` - stable `id` values in `repo@shortcommit` format - same authoritative source of truth used by later skills ## Milestone cross-check `changes.json` is derived from a VMR source-manifest diff. That makes it authoritative for *what flowed into the build*, but it is a commit-shaped view, and a feature can be easy to overlook in it. For the repos that maintain preview milestones, sweep the milestone as a **second, independent view** of the same release and reconcile anything that looks like a user-facing feature but never made it into the notes. ```bash gh api -X GET search/issues \ -f q="repo:dotnet/aspnetcore is:pr is:merged milestone:11.0-preview7" \ --jq '.total_count' ``` Milestone discipline varies by repo, so this check only applies for the repos where it is actually maintained: - dotnet/sdk - dotnet/aspnetcore - dotnet/runtime - dotnet/efcore Rules for using it: - **Supplement, never replace.** `changes.json` stays the source of truth. The milestone is a prompt to go back and look, not an alternative manifest. - **The milestone is a subset.** It excludes infrastructure and dependency-flow PRs that legitimately appear in `changes.json`, so the counts will not match and are not meant to. - **Only the missing direction matters.** What is worth acting on is a PR in the milestone that describes a user-facing change and has no corresponding entry in the notes. - **Verify every addition independently before writing it up.** Milestones are applied by automation, so they are usually right — but they can be changed or applied incorrectly by hand afterwards, and a milestoned PR can still be reverted. Treat a milestone as reliable evidence of where to look and strong but not conclusive evidence that the change shipped. Before promoting anything found this way, confirm it appears in `changes.json` and exists in the build (see [`api-verification.md`](../release-notes/references/api-verification.md) and [`validate-code-samples`](../validate-code-samples/SKILL.md)). The expected outcome is that it checks out; the point is to catch the occasional one that does not. - **Confirm the milestone exists before relying on its absence.** Repos without `11.x` milestones will return zero results, which means "not tracked here", not "nothing shipped". Once `changes.json` exists, the next step is usually `generate-features`.