Skip to content

Update breaking-change-guidelines.md #47797

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aortiz-msft merged 1 commit into from
Mar 26, 2025
Merged

Update breaking-change-guidelines.md #47797

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions documentation/project-docs/breaking-change-guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,9 @@ This document provides guidelines for introducing new diagnostics or breaking ch

## General guidance

In general, we want to make updating the .NET SDK as smooth as possible for developers. This means:
In general, we want to make updating the .NET SDK as smooth as possible for developers. This extends to .NET tooling such as IDEs and code editors which may have a different release schedule and cadence. For example, the .NET 9 SDK (which was a new major version) was released with Visual Studio 17.12 (which was a new minor version). In this example, breaking changes in the .NET 9 SDK could disproportionally impact Visual Studio users who are expecting incremental, non-breaking, changes in the new minor version. Same applies to other IDEs and code editors from the wider .NET community.

This means:
* Introducing new changes in a staged/gradual way.
* Tying new analyzers/diagnostics to a mechanism that requires explicit opt-in.
* Providing a way to opt out of a change entirely.
Expand Down Expand Up @@ -84,5 +85,5 @@ Specific example: NuGet warnings for vulnerable transitive dependencies were int

* Create an issue in the appropriate GitHub repository to track the change, if one does not already exist.
* Add the breaking-change label to the issue. This label should be available in all .NET repositories that ship as part of the .NET SDK. If the label is not available, please file an issue in [dotnet/sdk](https://github.com/dotnet/sdk).
* The issue will trigger a message with instructions to add documentation. In addition, you are invited to work with the SDK team to publish a blog post for the change.
* Consider creating and pinning an issue in the appropriate GitHub repository where the community can provide feedback.
* Once a Pull Request is submitted for the issue, add the breaking-change label to the Pull Request as well. This will trigger a message with instructions. In addition, you are invited to work with the SDK team to publish a blog post for the change.
Copy link
Member

@marcpopMSFT marcpopMSFT Mar 21, 2025

Choose a reason for hiding this comment

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

Should there be a link to the docs repo where the breaking change would be filed or leave that to the instructions?