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:

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:

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 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

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:

# 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:

• 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.

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 and validate-code-samples). 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.