Imported Upstream version 5.16.0.100

Former-commit-id: 38faa55fb9669e35e7d8448b15c25dc447f25767

external/corefx/Documentation/coding-guidelines/adding-api-guidelines.md

@@ -137,4 +137,4 @@ where you removed types in order to maintain back-compat.
 - Remove old build configurations - The older build configurations will automatically be harvested from
 the last stable packages and thus can be removed.
 - Remove import statements - If not referencing any pre-netstandard stable packages the [imports of dotnet5.x](https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Process/src/project.json#L28) are no longer needed and can be removed. We should also remove any dead target frameworks sections.
-- Remove all non-conditionsed `<AssemblyVersion>` properties from csproj's as it should be defined in library\dir.props.
+- Remove all non-conditioned `<AssemblyVersion>` properties from csproj's as it should be defined in library\dir.props.

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:

external/corefx/Documentation/coding-guidelines/coding-style.md

@@ -9,10 +9,10 @@ The general rule we follow is "use Visual Studio defaults".
 
 1. We use [Allman style](http://en.wikipedia.org/wiki/Indent_style#Allman_style) braces, where each brace begins on a new line. A single line statement block can go without braces but the block must be properly indented on its own line and it must not be nested in other statement blocks that use braces (See issue [381](https://github.com/dotnet/corefx/issues/381) for examples). 
 2. We use four spaces of indentation (no tabs).
-3. We use `_camelCase` for internal and private fields and use `readonly` where possible. Prefix instance fields with `_`, static fields with `s_` and thread static fields with `t_`. When used on static fields, `readonly` should come after `static` (i.e. `static readonly` not `readonly static`).
+3. We use `_camelCase` for internal and private fields and use `readonly` where possible. Prefix instance fields with `_`, static fields with `s_` and thread static fields with `t_`. When used on static fields, `readonly` should come after `static` (e.g. `static readonly` not `readonly static`).
 4. We avoid `this.` unless absolutely necessary. 
-5. We always specify the visibility, even if it's the default (i.e.
-   `private string _foo` not `string _foo`). Visibility should be the first modifier (i.e. 
+5. We always specify the visibility, even if it's the default (e.g.
+   `private string _foo` not `string _foo`). Visibility should be the first modifier (e.g. 
    `public abstract` not `abstract public`).
 6. Namespace imports should be specified at the top of the file, *outside* of
    `namespace` declarations and should be sorted alphabetically.
@@ -23,12 +23,13 @@ The general rule we follow is "use Visual Studio defaults".
    Consider enabling "View White Space (Ctrl+E, S)" if using Visual Studio, to aid detection.
 9. If a file happens to differ in style from these guidelines (e.g. private members are named `m_member`
    rather than `_member`), the existing style in that file takes precedence.
-10. We only use `var` when it's obvious what the variable type is (i.e. `var stream = new FileStream(...)` not `var stream = OpenStandardInput()`).
-11. We use language keywords instead of BCL types (i.e. `int, string, float` instead of `Int32, String, Single`, etc) for both type references as well as method calls (i.e. `int.Parse` instead of `Int32.Parse`). See issue [391](https://github.com/dotnet/corefx/issues/391) for examples.
+10. We only use `var` when it's obvious what the variable type is (e.g. `var stream = new FileStream(...)` not `var stream = OpenStandardInput()`).
+11. We use language keywords instead of BCL types (e.g. `int, string, float` instead of `Int32, String, Single`, etc) for both type references as well as method calls (e.g. `int.Parse` instead of `Int32.Parse`). See issue [391](https://github.com/dotnet/corefx/issues/391) for examples.
 12. We use PascalCasing to name all our constant local variables and fields. The only exception is for interop code where the constant value should exactly match the name and value of the code you are calling via interop.
 13. We use ```nameof(...)``` instead of ```"..."``` whenever possible and relevant.
 14. Fields should be specified at the top within type declarations.
 15. When including non-ASCII characters in the source code use Unicode escape sequences (\uXXXX) instead of literal characters. Literal non-ASCII characters occasionally get garbled by a tool or editor.
+16. When using labels (for goto), indent the label one less than the current indentation.
 
 We have provided a Visual Studio 2013 vssettings file (`corefx.vssettings`) at the root of the corefx repository, enabling C# auto-formatting conforming to the above guidelines. Note that rules 7 and 8 are not covered by the vssettings, since these are not rules currently supported by VS formatting.