diff options
author | Immo Landwerth <immol@microsoft.com> | 2016-11-17 22:16:59 +0300 |
---|---|---|
committer | Immo Landwerth <immol@microsoft.com> | 2016-11-17 22:16:59 +0300 |
commit | 649887fe4cb8356c0432133b34cc3cfa688c4b43 (patch) | |
tree | 716f79dfc0534a4061fe6b6f14a6ed424f066d2e /Documentation/coding-guidelines | |
parent | 5584f051ed26d61417e99cfac4ef514aa55a7a94 (diff) |
Minor fixes to wording
Diffstat (limited to 'Documentation/coding-guidelines')
-rw-r--r-- | Documentation/coding-guidelines/breaking-changes.md | 32 |
1 files changed, 15 insertions, 17 deletions
diff --git a/Documentation/coding-guidelines/breaking-changes.md b/Documentation/coding-guidelines/breaking-changes.md index ecf7384661..2d72223c0d 100644 --- a/Documentation/coding-guidelines/breaking-changes.md +++ b/Documentation/coding-guidelines/breaking-changes.md @@ -1,19 +1,19 @@ # Breaking Changes -We take compatibility in the .NET Framework and .NET Core extremely seriously. +We take compatibility in .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. +portable libraries can target it and still run on .NET Framework as well. This +means that the behavior of .NET Framework can constrain the implementation of +any overlapping APIs 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. -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 APIs that have shipped in a previous RTM +release. New APIs still under development can be modified but we are still +cautious not to disrupt the ecosystem unnecessarily when prerelease APIs change. To help triage breaking changes, we classify them in to four buckets: @@ -30,8 +30,8 @@ Examples: * 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 +* Adding an interface to the set of base types of an interface +* Removing a type or interface from the set of base types * Changing the return type of a member * ...or any other [incompatible change][breaking-change] to the shape of an API @@ -64,8 +64,8 @@ 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 changes in bucket 2, 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 @@ -91,8 +91,7 @@ more latitude here in .NET Core. - 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. +* If you're not sure which bucket applies to a given change, contact us. ### Risk-Benefit Analysis @@ -102,13 +101,12 @@ can result in one of the following outcomes: * **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. + old behavior if necessary. * **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. + benefit is large and the risk is super low or if the risk is moderate and a + compat switch 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. - |