You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: documentation/project-docs/breaking-change-guidelines.md
+11-8Lines changed: 11 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,24 +2,25 @@
2
2
3
3
This document provides guidelines for introducing new diagnostics or breaking changes to the .NET SDK, which configuration knobs are available, what criteria should guide the decision around severity, timeline for introduction, and deprecation of diagnostics, and what steps are required by the .NET release process.
4
4
5
+
## What is a breaking change in the .NET SDK?
6
+
7
+
A .NET SDK breaking change is when a customer upgrades to a newer .NET SDK, while changing nothing else in their environment, and experiences a disruption to their product build or execution.
8
+
5
9
## General guidance
6
10
7
-
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.
11
+
In general, we want to make updating the .NET SDK as smooth as possible for developers. This extends to updating .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.
8
12
9
13
This means:
10
14
* Introducing new changes in a staged/gradual way.
11
15
* Tying new analyzers/diagnostics to a mechanism that requires explicit opt-in.
12
16
* Providing a way to opt out of a change entirely.
13
17
14
-
## Kinds of .NET SDK breaking changes
15
-
16
-
There are many kinds of breaking changes that can ship in the .NET SDK, such as:
18
+
## Examples of .NET SDK breaking changes
17
19
18
20
* New MSBuild warnings and errors (props/targets).
19
21
* New NuGet warnings and errors.
20
22
* For example, NuGet Audit.
21
-
* Roslyn Analyzers and CodeFixes.
22
-
* This includes trimming/ILLink analyzers and codefixes.
23
+
* Changes to Roslyn Analyzers and CodeFixes that apply to existing TFMs.
23
24
* Behavioral/implementation changes.
24
25
* MSBuild engine changes like MSBuild Server.
25
26
* Implementation changes for MSBuild Tasks.
@@ -77,9 +78,11 @@ This knob exists so that users can safely and consistently say "for whatever rea
77
78
78
79
### Tie potentially impactful changes to the target TFM
79
80
80
-
Changes that are expected to cause significant disruption should only be introduced behind the Target Framework knob. This ensures business continuity and allows developers to address changes needed as part of scheduled work to migrate a codebase to a new TFM.
81
+
Changes that are expected to cause significant disruption should only be introduced behind the Target Framework knob. This ensures business continuity and allows developers to address changes needed as part of scheduled work to migrate a codebase to a new TFM. In general, new warnings/errors that only apply to a new TFM are not considered breaking changes.
81
82
82
-
Specific example: NuGet warnings for vulnerable transitive dependencies were introduced in the .NET 10 SDK only for applications targeting .NET 10 and higher.
83
+
Examples:
84
+
* NuGet warnings for vulnerable transitive dependencies were introduced in the .NET 10 SDK only for projects targeting .NET 10 and higher.
85
+
* New Roslyn analyzers tied to a new target TFM.
83
86
84
87
## Required process for all .NET SDK breaking changes
0 commit comments