dotnet · gewarren · Feb 12, 2021 · Feb 11, 2021 · Feb 11, 2021
diff --git a/docs/core/compatibility/6.0.md b/docs/core/compatibility/6.0.md
@@ -17,6 +17,10 @@ If you're migrating an app to .NET 6.0, the breaking changes listed here might a
 - [Middleware: HTTPS Redirection Middleware throws exception on ambiguous HTTPS ports](aspnet-core/6.0/middleware-ambiguous-https-ports-exception.md)
 - [Razor: RazorEngine APIs marked obsolete](aspnet-core/6.0/razor-engine-apis-obsolete.md)
 
+## Core .NET libraries
+
+- [Changes to nullable reference type annotations](core-libraries/6.0/nullable-ref-type-annotation-changes.md)
+
 ## Windows Forms
 
 - [Selected TableLayoutSettings properties throw InvalidEnumArgumentException](windows-forms/6.0/tablelayoutsettings-apis-throw-invalidenumargumentexception.md)

diff --git a/docs/core/compatibility/core-libraries/6.0/nullable-ref-type-annotation-changes.md b/docs/core/compatibility/core-libraries/6.0/nullable-ref-type-annotation-changes.md
@@ -0,0 +1,94 @@
+---
+title: "Breaking change: Nullable reference type annotation changes"
+description: Learn about the .NET 6.0 breaking change in core .NET libraries where some nullable reference type annotations have changed.
+ms.date: 02/11/2021
+---
+# Changes to nullable reference type annotations
+
+In .NET 6.0, some nullability annotations in the .NET libraries have changed.
+
+## Change description
+
+In previous .NET versions, some nullable reference type annotations are incorrect, and build warnings are either absent or incorrect. Starting in .NET 6.0, some annotations that were previously applied have been updated. New build warnings will be produced and incorrect build warnings will no longer be produced for the affected APIs.
+
+Some of these changes are considered to be *breaking* because they can lead to new build-time warnings. When you migrate to .NET 6.0, code that references these APIs will need to be updated.
+
+Other changes that aren't considered to be breaking are also documented on this page. Any code that references the updated APIs may benefit from removing operators or pragmas that are no longer unnecessary.
+
+## Version introduced
+
+6.0
+
+## Reason for change
+
+Starting in .NET Core 3.0, nullability annotations were applied to the .NET libraries. From the outset of the effort, mistakes in these annotations were anticipated. Through feedback and further testing, the nullable annotations for the affected APIs were determined to be inaccurate. The updated annotations correctly represent the nullability contracts for the APIs.
+
+## Recommended action
+
+Update code that calls these APIs to reflect the revised nullability contracts.
+
+## Affected APIs
+
+The following table lists the affected APIs:
+
+| API | What changed | Breaking or nonbreaking | Version added |
+| - | - | - |
+| <xref:System.ComponentModel.ISite.Container?displayProperty=nameWithType> | Property type is nullable | Breaking | Preview 1 |
+| <xref:System.Xml.Linq.XContainer.Add(System.Object[])?displayProperty=nameWithType> | Parameter type is nullable | Nonbreaking | Preview 1 |
+| <xref:System.Xml.Linq.XContainer.AddFirst(System.Object[])?displayProperty=nameWithType> | Parameter type is nullable | Nonbreaking | Preview 1 |
+| <xref:System.Xml.Linq.XContainer.ReplaceNodes(System.Object[])?displayProperty=nameWithType> | Parameter type is nullable | Nonbreaking | Preview 1 |
+| <xref:System.Xml.Linq.XDocument.%23ctor(System.Object[])> | Parameter type is nullable | Nonbreaking | Preview 1 |
+| <xref:System.Xml.Linq.XDocument.%23ctor(System.Xml.Linq.XDeclaration,System.Object[])> | Parameter type is nullable | Nonbreaking | Preview 1 |
+| <xref:System.Xml.Linq.XElement.%23ctor(System.Xml.Linq.XName,System.Object[])> | Second parameter type is nullable | Nonbreaking | Preview 1 |
+| <xref:System.Xml.Linq.XElement.ReplaceAll(System.Object[])?displayProperty=nameWithType> | Parameter type is nullable | Nonbreaking | Preview 1 |
+| <xref:System.Xml.Linq.XElement.ReplaceAttributes(System.Object[])?displayProperty=nameWithType> | Parameter type is nullable | Nonbreaking | Preview 1 |
+| <xref:System.Xml.Linq.XNode.AddAfterSelf(System.Object[])?displayProperty=nameWithType> | Parameter type is nullable | Nonbreaking | Preview 1 |
+| <xref:System.Xml.Linq.XNode.AddBeforeSelf(System.Object[])?displayProperty=nameWithType> | Parameter type is nullable | Nonbreaking | Preview 1 |
+| <xref:System.Xml.Linq.XNode.ReplaceWith(System.Object[])?displayProperty=nameWithType> | Parameter type is nullable | Nonbreaking | Preview 1 |
+| <xref:System.Xml.Linq.XStreamingElement.%23ctor(System.Xml.Linq.XName,System.Object)> | Second parameter type is nullable | Nonbreaking | Preview 1 |
+| <xref:System.Xml.Linq.XStreamingElement.%23ctor(System.Xml.Linq.XName,System.Object[])> | Second parameter type is nullable | Nonbreaking | Preview 1 |
+| <xref:System.Xml.Linq.XStreamingElement.Add(System.Object[])?displayProperty=nameWithType> | Parameter type is nullable | Nonbreaking | Preview 1 |
+| <xref:System.Net.Http.HttpClient.PatchAsync%2A?displayProperty=nameWithType> | `content` parameter type is nullable | Nonbreaking | Preview 1 |
+| <xref:System.Net.Http.HttpClient.PostAsync%2A?displayProperty=nameWithType> | `content` parameter type is nullable  | Nonbreaking | Preview 1 |
+| <xref:System.Net.Http.HttpClient.PutAsync%2A?displayProperty=nameWithType> | `content` parameter type is nullable  | Nonbreaking | Preview 1 |
+| <xref:System.Linq.Expressions.MethodCallExpression.Update(System.Linq.Expressions.Expression,System.Collections.Generic.IEnumerable{System.Linq.Expressions.Expression})?displayProperty=nameWithType> | First parameter type is nullable | Nonbreaking | Preview 1 |
+| <xref:System.Linq.Expressions.Expression%601.Update(System.Linq.Expressions.Expression,System.Collections.Generic.IEnumerable{System.Linq.Expressions.ParameterExpression})?displayProperty=nameWithType> | Return type is not nullable | Nonbreaking | Preview 1 |
+| <xref:System.Data.IDataRecord.GetBytes(System.Int32,System.Int64,System.Byte[],System.Int32,System.Int32)?displayProperty=nameWithType> | `buffer` parameter type is nullable | Breaking | Preview 1 |
+| <xref:System.Data.IDataRecord.GetChars(System.Int32,System.Int64,System.Char[],System.Int32,System.Int32)?displayProperty=nameWithType> | `buffer` parameter type is nullable | Breaking | Preview 1 |
+| <xref:System.Data.Common.DbDataRecord.GetBytes(System.Int32,System.Int64,System.Byte[],System.Int32,System.Int32)?displayProperty=nameWithType> | `buffer` parameter type is nullable | Breaking | Preview 1 |
+| <xref:System.Data.Common.DbDataRecord.GetChars(System.Int32,System.Int64,System.Char[],System.Int32,System.Int32)?displayProperty=nameWithType> | `buffer` parameter type is nullable | Breaking | Preview 1 |
+
+<!--
+
+### Category
+
+Core .NET libraries
+
+### Affected APIs
+
+- `P:System.ComponentModel.ISite.Container`
+- `M:System.Xml.Linq.XContainer.Add(System.Object[])`
+- `M:System.Xml.Linq.XContainer.AddFirst(System.Object[])`
+- `M:System.Xml.Linq.XContainer.ReplaceNodes(System.Object[])`
+- `M:System.Xml.Linq.XDocument.#ctor(System.Object[])`
+- `M:System.Xml.Linq.XDocument.#ctor(System.Xml.Linq.XDeclaration,System.Object[])`
+- `M:System.Xml.Linq.XElement.#ctor(System.Xml.Linq.XName,System.Object[])`
+- `M:System.Xml.Linq.XElement.ReplaceAll(System.Object[])`
+- `M:System.Xml.Linq.XElement.ReplaceAttributes(System.Object[])`
+- `M:System.Xml.Linq.XNode.AddAfterSelf(System.Object[])`
+- `M:System.Xml.Linq.XNode.AddBeforeSelf(System.Object[])`
+- `M:System.Xml.Linq.XNode.ReplaceWith(System.Object[])`
+- `M:System.Xml.Linq.XStreamingElement.#ctor(System.Xml.Linq.XName,System.Object)`
+- `M:System.Xml.Linq.XStreamingElement.#ctor(System.Xml.Linq.XName,System.Object[])`
+- `M:System.Xml.Linq.XStreamingElement.Add(System.Object[])`
+- `O:System.Net.Http.HttpClient.PatchAsync`
+- `O:System.Net.Http.HttpClient.PostAsync`
+- `O:System.Net.Http.HttpClient.PutAsync`
+- `M:System.Linq.Expressions.MethodCallExpression.Update(System.Linq.Expressions.Expression,System.Collections.Generic.IEnumerable{System.Linq.Expressions.Expression})`
+- `M:System.Linq.Expressions.Expression%601.Update(System.Linq.Expressions.Expression,System.Collections.Generic.IEnumerable{System.Linq.Expressions.ParameterExpression})`
+- `M:System.Data.IDataRecord.GetBytes(System.Int32,System.Int64,System.Byte[],System.Int32,System.Int32)`
+- `M:System.Data.IDataRecord.GetChars(System.Int32,System.Int64,System.Char[],System.Int32,System.Int32)`
+- `M:System.Data.Common.DbDataRecord.GetBytes(System.Int32,System.Int64,System.Byte[],System.Int32,System.Int32)`
+- `M:System.Data.Common.DbDataRecord.GetChars(System.Int32,System.Int64,System.Char[],System.Int32,System.Int32)`
+
+-->
diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml
@@ -32,6 +32,10 @@
           href: aspnet-core/6.0/middleware-ambiguous-https-ports-exception.md
         - name: "Razor: RazorEngine APIs marked obsolete"
           href: aspnet-core/6.0/razor-engine-apis-obsolete.md
+      - name: Core .NET libraries
+        items:
+        - name: Nullability annotation changes
+          href: core-libraries/6.0/nullable-ref-type-annotation-changes.md
       - name: Windows Forms
         items:
         - name: APIs throw ArgumentNullException
@@ -418,6 +422,10 @@
           href: code-analysis/5.0/ca2247-ctor-arg-should-be-taskcreationoptions.md
     - name: Core .NET libraries
       items:
+      - name: .NET 6.0
+        items:
+        - name: Nullability annotation changes
+          href: core-libraries/6.0/nullable-ref-type-annotation-changes.md
       - name: .NET 5.0
         items:
         - name: Assembly-related API changes for single-file publishing