Generate `changes.json` for a .NET release milestone by selecting the correct VMR base/head refs and running `release-notes generate changes`. Handles preview-only multi-branch targeting (`main` vs release branches vs tags) and emits the authoritative manifest of what shipped. DO NOT USE FOR: API verification/diffs (use api-diff), feature scoring (use generate-features), or writing markdown release notes (use release-notes).
changes.jsonProduce 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:
--base and --head refsrelease-notes generate changeschanges.json into the correct release-notes/ folderchanges.json is missing, stale, or suspected to have the wrong ref selectionThis is the subtle part, and it mostly matters for previews.
Multiple preview milestones can be active simultaneously:
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.
The user should provide as much of this as they know:
.NET 11 Preview 4, .NET 10 RC 2, .NET 10 GAdotnet/dotnetIf the user does not specify the milestone, infer it from:
release-notes/{version}/releases.json in this repoeng/Versions.props on main in the VMRreleases.jsonFind the latest shipped milestone in this repo. That tells you the lowest in-flight milestone that may need work.
eng/Versions.props on main to determine the current prerelease iterationUse the VMR structure reference for naming conventions and branch patterns.
--base and --headFor each active milestone:
--base is the previous shipped milestone tag--head is the milestone tag, release branch tip, or main, depending on what existsrelease-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:
# 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
The output file must follow the shared schema documented in changes-schema.md:
release_version, release_date, changes, commitsid values in repo@shortcommit formatOnce changes.json exists, the next step is usually generate-features.