From ab308102686ceb38a26a7a9043b4f25c41760bdd Mon Sep 17 00:00:00 2001 From: Immo Landwerth Date: Wed, 16 Nov 2016 11:01:56 -0800 Subject: Apply Markdown conventions to breaking-changes.md Use line breaks and consistent headings so that code reviews are easier. --- .../coding-guidelines/breaking-changes.md | 66 ++++++++++++++-------- 1 file changed, 44 insertions(+), 22 deletions(-) (limited to 'Documentation') diff --git a/Documentation/coding-guidelines/breaking-changes.md b/Documentation/coding-guidelines/breaking-changes.md index 1f6b1d0609..8220e90171 100644 --- a/Documentation/coding-guidelines/breaking-changes.md +++ b/Documentation/coding-guidelines/breaking-changes.md @@ -1,13 +1,19 @@ -Breaking Changes -================ +# Breaking Changes We take compatibility in the .NET Framework and .NET Core extremely seriously. -Although .NET Core can be deployed app local, we are engineering it such that portable libraries can target it and still run on the full desktop framework as well. This means that the behavior of the full .NET Framework constrains the implementation of any overlapping API in .NET Core. +Although .NET Core can be deployed app local, we are engineering it such that +portable libraries can target it and still run on the full desktop framework as +well. This means that the behavior of the full .NET Framework constrains the +implementation of any overlapping API in .NET Core. -Below is a summary of some documentation we have internally about what kinds of things constitute breaking changes, how we categorize them, and how we decide what we're willing to take. +Below is a summary of some documentation we have internally about what kinds of +things constitute breaking changes, how we categorize them, and how we decide +what we're willing to take. -Note that these rules only apply to API that have shipped in a previous RTM release. New API still under development can be modified but we are still cautious not to disrupt the ecosystem unnecessarily when prerelease API change. +Note that these rules only apply to API that have shipped in a previous RTM +release. New API still under development can be modified but we are still +cautious not to disrupt the ecosystem unnecessarily when prerelease API change. To help triage breaking changes, we classify them in to four buckets: @@ -16,7 +22,7 @@ To help triage breaking changes, we classify them in to four buckets: 3. Unlikely Grey Area 4. Clearly Non-Public -### Bucket 1: Public Contract +## Bucket 1: Public Contract *Clear violation of public contract.* Examples: @@ -28,35 +34,51 @@ Examples: * A new instance field is added to a type (impacts serialization) * changing the value of a public constant or enum member -### Bucket 2: Reasonable Grey Area +## Bucket 2: Reasonable Grey Area *Change of behavior that customers would have reasonably depended on.* Examples: + * change in timing/order of events (even when not specified in docs) -* change in parsing of input and throwing new errors (even if parsing behavior is not specified in the docs) +* change in parsing of input and throwing new errors (even if parsing behavior + is not specified in the docs) These require judgment: how predictable, obvious, consistent was the behavior? -### Bucket 3: Unlikely Grey Area -*Change of behavior that customers could have depended on, but probably wouldn't.* +## Bucket 3: Unlikely Grey Area +*Change of behavior that customers could have depended on, but probably* +*wouldn't.* + +Examples: -**Examples:** * correcting behavior in a subtle corner case -As with type 2 changes, these require judgment: what is reasonable and what’s not? +As with type 2 changes, these require judgment: what is reasonable and what’s +not? -### Bucket 4: Clearly Non-Public -*Changes to surface area or behavior that is clearly internal or non-breaking in theory, but breaks an app.* +## Bucket 4: Clearly Non-Public +*Changes to surface area or behavior that is clearly internal or non-breaking* +*in theory, but breaks an app.* + +Examples: -**Examples:** * Changes to internal API that break private reflection -It is impossible to evolve a code base without making such changes, so we don't require up-front approval for these, but we will sometimes have to go back and revisit such change if there's too much pain inflicted on the ecosystem through a popular app or library. +It is impossible to evolve a code base without making such changes, so we don't +require up-front approval for these, but we will sometimes have to go back and +revisit such change if there's too much pain inflicted on the ecosystem through +a popular app or library. + +This bucket is painful for the machine-wide .NET Framework, but we do have much +more latitude here in .NET Core. -This bucket is painful for the machine-wide .NET Framework, but we do have much more latitude here in .NET Core. +## What This Means for Contributors -### What This Means for Contributors -* All bucket 1, 2, and 3 breaking changes require talking to the repo owners first. -* If you're not sure in which bucket applies to a given change, contact us as well. -* It doesn't matter if the old behavior is "wrong", we still need to think through the implications. -* If a change is deemed too breaking, we can help identify alternatives such as introducing a new API and obsoleting the old one. +* All bucket 1, 2, and 3 breaking changes require talking to the repo owners + first. +* If you're not sure in which bucket applies to a given change, contact us as + well. +* It doesn't matter if the old behavior is "wrong", we still need to think + through the implications. +* If a change is deemed too breaking, we can help identify alternatives such as + introducing a new API and obsoleting the old one. -- cgit v1.2.3 From 3b782dcd5f8b64573ced1db3ec3cc60f56c985e7 Mon Sep 17 00:00:00 2001 From: Immo Landwerth Date: Wed, 16 Nov 2016 11:12:41 -0800 Subject: Move quirkable behavioral changes to bucket 2 --- Documentation/coding-guidelines/breaking-changes.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/coding-guidelines/breaking-changes.md b/Documentation/coding-guidelines/breaking-changes.md index 8220e90171..44cb34e4ee 100644 --- a/Documentation/coding-guidelines/breaking-changes.md +++ b/Documentation/coding-guidelines/breaking-changes.md @@ -26,12 +26,7 @@ To help triage breaking changes, we classify them in to four buckets: *Clear violation of public contract.* Examples: -* throwing a new/different exception type in an existing common scenario -* An exception is no longer thrown -* A different behavior is observed after the change for an input * renaming a public type, member, or parameter -* decreasing the range of accepted values within a given parameter -* A new instance field is added to a type (impacts serialization) * changing the value of a public constant or enum member ## Bucket 2: Reasonable Grey Area @@ -39,6 +34,11 @@ Examples: Examples: +* throwing a new/different exception type in an existing common scenario +* An exception is no longer thrown +* A different behavior is observed after the change for an input +* decreasing the range of accepted values within a given parameter +* A new instance field is added to a type (impacts serialization) * change in timing/order of events (even when not specified in docs) * change in parsing of input and throwing new errors (even if parsing behavior is not specified in the docs) -- cgit v1.2.3 From 68e4910490193ded2152f69fca2135caeda14b02 Mon Sep 17 00:00:00 2001 From: Immo Landwerth Date: Wed, 16 Nov 2016 11:13:19 -0800 Subject: Add clarification for contributors --- .../coding-guidelines/breaking-changes.md | 33 ++++++++++++++++++---- 1 file changed, 28 insertions(+), 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/coding-guidelines/breaking-changes.md b/Documentation/coding-guidelines/breaking-changes.md index 44cb34e4ee..820b48da9b 100644 --- a/Documentation/coding-guidelines/breaking-changes.md +++ b/Documentation/coding-guidelines/breaking-changes.md @@ -75,10 +75,33 @@ more latitude here in .NET Core. ## What This Means for Contributors * All bucket 1, 2, and 3 breaking changes require talking to the repo owners - first. + first: + - We generally **don't accept** change proposals that are in bucket #1. + - We **might accept** change proposals that are in #2 and #3 after a + risk-benefit analysis. See below for more details. + - We **usually accept** changes that are in bucket #4 * If you're not sure in which bucket applies to a given change, contact us as well. -* It doesn't matter if the old behavior is "wrong", we still need to think - through the implications. -* If a change is deemed too breaking, we can help identify alternatives such as - introducing a new API and obsoleting the old one. + +### Risk-Benefit Analysis + +For buckets #2 and #3 we apply a risk-benefit analysis. It doesn't matter if the +old behavior is "wrong", we still need to think through the implications. This +can result in one of the following outcomes: + +* **Accepted with quirking**. Depending on the estimated customer impact, we may + decide to "quirk" the behavior. That means, that the new behavior is only + exposed to apps that are compiled against the version of .NET Core that + introduced the change. In other words, apps running against a shared framework + will not see the behavior if they were compiled against an older version of + .NET Core and thus wouldn't have been tested in the context of the behavioral + change. + +* **Accepted**. In some minor cases, we may decide to accept the change if the + the benefit is large and the risk is super low or if the risk is moderate and + quirking isn't viable. + +* **Rejected**. If the risk is too high and/or the improvement too minor, we may + decide not to accept the change proposal at all. We can help identify + alternatives such as introducing a new API and obsoleting the old one. + -- cgit v1.2.3 From 531e402f5a145c378229d8cf34e86cb98d99237c Mon Sep 17 00:00:00 2001 From: Immo Landwerth Date: Wed, 16 Nov 2016 15:13:07 -0800 Subject: Address Dan's feedback --- Documentation/coding-guidelines/breaking-changes.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/coding-guidelines/breaking-changes.md b/Documentation/coding-guidelines/breaking-changes.md index 820b48da9b..aff6f4bf21 100644 --- a/Documentation/coding-guidelines/breaking-changes.md +++ b/Documentation/coding-guidelines/breaking-changes.md @@ -23,14 +23,23 @@ To help triage breaking changes, we classify them in to four buckets: 4. Clearly Non-Public ## Bucket 1: Public Contract -*Clear violation of public contract.* +*Clear [violation][breaking-change] of public contract.* Examples: -* renaming a public type, member, or parameter +* renaming or removing of a public type, member, or parameter * changing the value of a public constant or enum member +* sealing a type that wasn't sealed +* making a virtual member abstract +* adding an interface to the set of base types of an interfaces +* removing a type or interface from the the of base types +* changing the return type of a member +* ...or any other [incompatible change][breaking-change] to the shape of an API + +[breaking-change]: breaking-change-rules.md#source-and-binary-compatibility-changes ## Bucket 2: Reasonable Grey Area -*Change of behavior that customers would have reasonably depended on.* +*[Change of behavior][behavioral-changes] that customers would have reasonably* +*depended on.* Examples: @@ -45,6 +54,8 @@ Examples: These require judgment: how predictable, obvious, consistent was the behavior? +[behavioral-changes]: breaking-change-rules.md#behavioral-changes + ## Bucket 3: Unlikely Grey Area *Change of behavior that customers could have depended on, but probably* *wouldn't.* -- cgit v1.2.3 From a208342bd287e76d8b885f5ae40f9d1891f03ad0 Mon Sep 17 00:00:00 2001 From: Immo Landwerth Date: Wed, 16 Nov 2016 15:35:54 -0800 Subject: Address Sam's feedback --- .../coding-guidelines/breaking-changes.md | 36 +++++++++++----------- 1 file changed, 18 insertions(+), 18 deletions(-) (limited to 'Documentation') diff --git a/Documentation/coding-guidelines/breaking-changes.md b/Documentation/coding-guidelines/breaking-changes.md index aff6f4bf21..9f2c3125bc 100644 --- a/Documentation/coding-guidelines/breaking-changes.md +++ b/Documentation/coding-guidelines/breaking-changes.md @@ -23,33 +23,33 @@ To help triage breaking changes, we classify them in to four buckets: 4. Clearly Non-Public ## Bucket 1: Public Contract -*Clear [violation][breaking-change] of public contract.* +*Clear [violation of public contract][breaking-change].* Examples: -* renaming or removing of a public type, member, or parameter -* changing the value of a public constant or enum member -* sealing a type that wasn't sealed -* making a virtual member abstract -* adding an interface to the set of base types of an interfaces -* removing a type or interface from the the of base types -* changing the return type of a member +* Renaming or removing of a public type, member, or parameter +* Changing the value of a public constant or enum member +* Sealing a type that wasn't sealed +* Making a virtual member abstract +* Adding an interface to the set of base types of an interfaces +* Removing a type or interface from the the of base types +* Changing the return type of a member * ...or any other [incompatible change][breaking-change] to the shape of an API [breaking-change]: breaking-change-rules.md#source-and-binary-compatibility-changes ## Bucket 2: Reasonable Grey Area -*[Change of behavior][behavioral-changes] that customers would have reasonably* -*depended on.* +*[Change of behavior][behavioral-changes] that customers would have reasonably +depended on.* Examples: -* throwing a new/different exception type in an existing common scenario +* Throwing a new/different exception type in an existing common scenario * An exception is no longer thrown * A different behavior is observed after the change for an input * decreasing the range of accepted values within a given parameter * A new instance field is added to a type (impacts serialization) -* change in timing/order of events (even when not specified in docs) -* change in parsing of input and throwing new errors (even if parsing behavior +* Change in timing/order of events (even when not specified in docs) +* Change in parsing of input and throwing new errors (even if parsing behavior is not specified in the docs) These require judgment: how predictable, obvious, consistent was the behavior? @@ -57,19 +57,19 @@ These require judgment: how predictable, obvious, consistent was the behavior? [behavioral-changes]: breaking-change-rules.md#behavioral-changes ## Bucket 3: Unlikely Grey Area -*Change of behavior that customers could have depended on, but probably* -*wouldn't.* +*Change of behavior that customers could have depended on, but probably +wouldn't.* Examples: -* correcting behavior in a subtle corner case +* Correcting behavior in a subtle corner case As with type 2 changes, these require judgment: what is reasonable and what’s not? ## Bucket 4: Clearly Non-Public -*Changes to surface area or behavior that is clearly internal or non-breaking* -*in theory, but breaks an app.* +*Changes to surface area or behavior that is clearly internal or non-breaking +in theory, but breaks an app.* Examples: -- cgit v1.2.3 From e9aefe1fce9010d4de0bf00e85d21817055efc3b Mon Sep 17 00:00:00 2001 From: Immo Landwerth Date: Wed, 16 Nov 2016 16:05:58 -0800 Subject: Change wording after talking to Alex --- Documentation/coding-guidelines/breaking-changes.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) (limited to 'Documentation') diff --git a/Documentation/coding-guidelines/breaking-changes.md b/Documentation/coding-guidelines/breaking-changes.md index 9f2c3125bc..ecf7384661 100644 --- a/Documentation/coding-guidelines/breaking-changes.md +++ b/Documentation/coding-guidelines/breaking-changes.md @@ -100,13 +100,9 @@ For buckets #2 and #3 we apply a risk-benefit analysis. It doesn't matter if the old behavior is "wrong", we still need to think through the implications. This can result in one of the following outcomes: -* **Accepted with quirking**. Depending on the estimated customer impact, we may - decide to "quirk" the behavior. That means, that the new behavior is only - exposed to apps that are compiled against the version of .NET Core that - introduced the change. In other words, apps running against a shared framework - will not see the behavior if they were compiled against an older version of - .NET Core and thus wouldn't have been tested in the context of the behavioral - change. +* **Accepted with compat switch**. Depending on the estimated customer impact, + we may decide to add a compat switch that allows consumers to bring back the + old behavior if neessary. * **Accepted**. In some minor cases, we may decide to accept the change if the the benefit is large and the risk is super low or if the risk is moderate and -- cgit v1.2.3