Skip to content

Use incremental API diffs for preview migration guidance - #10599

Merged
danroth27 merged 5 commits into
mainfrom
release-notes/preview-api-diff-guidance
Sep 26, 2026
Merged

danroth27 merged 5 commits into
mainfrom
release-notes/preview-api-diff-guidance

Conversation

@danroth27

@danroth27 danroth27 commented Sep 26, 2026 •

Copy link
Copy Markdown
Member

Summary

  • Review each preview or RC milestone's API diff for migration candidates (Preview 1 compares with the previous stable GA, while later milestones compare with the preceding prerelease); verify them against milestone PRs, changes.json, the build, and maintained samples rather than copying diff entries into release notes.
  • Separate Breaking changes from .NET N (N is the previous stable major version; version-to-version compatibility changes) from Changes since the previous preview (changes affecting only users of this major's earlier prereleases, including RCs). Include the former in preview notes and confirm coverage in the new version's aggregate compatibility documentation; omit empty sections and do not duplicate changes.
  • Cross-check the target version's .NET and ASP.NET Core compatibility indexes, open and closed announcement issues, and upstream breaking-change PRs. These sources may be incomplete or published after the change ships, so establish the milestone using changes.json and build evidence. Flag missing aggregate coverage to the component owner.
  • If the diff is unavailable, try generating it; if that fails, track the pending review on the base PR while drafting, and do not finalize without reviewing the report or recording a component-owner exception. Recheck pending diffs on populated milestone branches and incorporate newly published compatibility guidance even if the build has not changed.

This is separate from #10596, which covers where maintained samples live and how to validate them.

Validation

  • Targeted Markdown lint and link checks on the edited skill files passed; git diff --check passed.
  • Prettier reports formatting warnings for the edited files, consistent with the repository-wide baseline. Checkov could not run: Checkov and a Python installer are unavailable on this machine.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 637615df-deba-4407-bf00-9a3bd4e569b5
Use compatibility catalogs, announcements, implementation PRs, changes.json, and build evidence to identify version-to-version breaks without treating any source as complete.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 637615df-deba-4407-bf00-9a3bd4e569b5
@danroth27
danroth27 requested a balanced review from Copilot September 26, 2026 16:33

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Note

This error may be related to your runner configuration. You can now configure runners for Copilot code review separately from Copilot cloud agent by creating a copilot-code-review.yml file with your setup steps. Read the docs for details.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

Unresolved guidance gaps remain across the reviewed documentation.

Review effort: Lite
Findings: 2 Low severity

Open (2)

Comment thread .github/skills/release-notes/references/api-verification.md Outdated
Comment thread .github/skills/release-notes/references/api-verification.md Outdated
Select the GA baseline for Preview 1, use versioned compatibility indexes, and track failed diff generation through release-note reruns.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 637615df-deba-4407-bf00-9a3bd4e569b5

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🔵 Needs a closer look

Review comments identify unresolved baseline-separation and incremental-report guidance issues.

Review effort: Lite
Findings: None

Resolved since last review (2)
Previously missed (1)

In code that hasn't changed since last review

Low severity Require comparison against both stable and prior preview baselines

.github/​skills/​release-notes/​references/​changes-schema.md:122

This sentence only directs the writer to compare against the previous stable release, which is insufficient to distinguish a preview-only migration: an API or behavior introduced in Preview 6 and changed in Preview 7 must also be compared with Preview 6. The neighboring upgrade guidance requires both baselines; otherwise breaking_changes: true entries can be put in the wrong section.

@danroth27
danroth27 marked this pull request as ready for review September 26, 2026 16:53
Keep incremental API-diff migration guidance alongside the milestone index and maintained-sample instructions.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7e7e9011-e85b-469d-88f5-7843d1de691f

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

The workflow prompt and two API-verification guidance details need correction.

Review effort: Lite
Findings: 1 Medium severity · 1 Low severity

Open (2)

Comment thread .github/skills/release-notes/SKILL.md
Comment thread .github/skills/release-notes/references/changes-schema.md Outdated
Compare first previews with the previous stable release and later prereleases with both stable and preceding shipped prerelease baselines.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7e7e9011-e85b-469d-88f5-7843d1de691f

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🔵 Needs a closer look

Address the unresolved GA baseline, attribution, empty-section, and first-preview rerun guidance gaps.

Review effort: Lite
Findings: None

Resolved since last review (2)

@danroth27
danroth27 merged commit 4f5c7b9 into main Sep 26, 2026
7 checks passed
@danroth27
danroth27 deleted the release-notes/preview-api-diff-guidance branch September 26, 2026 20:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants