Imported Upstream version 5.16.0.100

Former-commit-id: 38faa55fb9669e35e7d8448b15c25dc447f25767

external/corefx/Documentation/coding-guidelines/breaking-change-rules.md

@@ -49,11 +49,12 @@ Breaking Change Rules
 > For example, `CultureInfo.GetCultureInfo(String)` used to throw `ArgumentException` in .NET Framework 3.5. In .NET Framework 4.0, this was changed to throw `CultureNotFoundException` which derives from `ArgumentException`, and therefore is an acceptable change.
 
 * Throwing a more specific exception than `NotSupportedException`, `NotImplementedException`, `NullReferenceException` or an exception that is considered unrecoverable  
-> Unrecoverable exceptions should not be getting caught and will be dealt with on a broad level by a high-level catch-all handler. Therefore, users are not expected to have code that catches these explicit exceptions. The list of unrecoverable exceptions are:
-     * `StackOverflowException`
-     * `SEHException`
-     * `ExecutionEngineException`
-     * `AccessViolationException`
+> Unrecoverable exceptions should not be getting caught and will be dealt with on a broad level by a high-level catch-all handler. Therefore, users are not expected to have code that catches these explicit exceptions. The unrecoverable exceptions are:
+>
+> * `StackOverflowException`
+> * `SEHException`
+> * `ExecutionEngineException`
+> * `AccessViolationException`
 
 * Throwing a new exception that only applies to a code-path which can only be observed with new parameter values, or state (that couldn't hit by existing code targeting the previous version)
 
@@ -131,6 +132,8 @@ Breaking Change Rules
 * Moving a type from one assembly into another assembly  
 > The old assembly must be marked with `TypeForwardedToAttribute` pointing to the new location
 
+* Changing a `struct` type to a `readonly struct` type
+
 ✗ **Disallowed**
 * Adding the `sealed` or `abstract` keyword to a type when there _are accessible_ (public or protected) constructors
 
@@ -143,6 +146,10 @@ Breaking Change Rules
 
 * Changing the namespace or name of a type
 
+* Changing a `readonly struct` type to a `struct` type
+
+* Changing a `struct` type to a `ref struct` type and vice versa
+
 ### Members
 ✓ **Allowed**
 * Adding an abstract member to a public type when there are _no accessible_ (`public` or `protected`) constructors, or the type is `sealed`
@@ -158,6 +165,8 @@ Breaking Change Rules
 * Introducing or removing an override
 > Make note, that introducing an override might cause previous consumers to skip over the override when calling `base`.
 
+* Change from `ref readonly` return to `ref` return (except for virtual methods or interfaces)
+
 ✗ **Disallowed**
 * Adding an member to an interface
 
@@ -180,6 +189,10 @@ successfully bind to that overload, if simply passing an `int` value. However, i
 * Adding `virtual` to a member
 > While this change would often work without breaking too many scenarios because C# compiler tends to emit `callvirt` IL instructions to call non-virtual methods (`callvirt` performs a null check, while a normal `call` won't), we can't rely on it. C# is not the only language we target and the C# compiler increasingly tries to optimize `callvirt` to a normal `call` whenever the target method is non-virtual and the `this` is provably not null (such as a method accessed through the `?.` null propagation operator). Making a method virtual would mean that consumer code would often end up calling it non-virtually.
 
+* Change from `ref` return to `ref readonly` return
+
+* Change from `ref readonly` return to `ref` return on a virtual method or interface
+
 * Adding or removing `static` keyword from a member
 
 ### Signatures
@@ -199,7 +212,7 @@ successfully bind to that overload, if simply passing an `int` value. However, i
 
 * Removing `params` from a parameter
 
-* Adding or removing `out` or `ref` keywords from a parameter
+* Adding or removing `in`, `out`, or `ref` keywords from a parameter
 
 * Renaming a parameter (including case)  
 > This is considered breaking for two reasons: