Document obsolete Libuv transport breaking change

docs/core/compatibility/3.1-5.0.md

@@ -1,7 +1,7 @@
 ---
 title: Breaking changes, version 3.1 to 5.0
 description: Lists the breaking changes from version 3.1 to version 5.0 of .NET, ASP.NET Core, and EF Core.
-ms.date: 07/15/2020
+ms.date: 07/17/2020
 ---
 # Breaking changes for migration from version 3.1 to 5.0
 
@@ -21,6 +21,7 @@ If you're migrating from version 3.1 of .NET Core, ASP.NET Core, or EF Core to v
 - [Kestrel: Configuration changes at run time detected by default](#kestrel-configuration-changes-at-run-time-detected-by-default)
 - [Kestrel: Default supported TLS protocol versions changed](#kestrel-default-supported-tls-protocol-versions-changed)
 - [Kestrel: HTTP/2 disabled over TLS on incompatible Windows versions](#kestrel-http2-disabled-over-tls-on-incompatible-windows-versions)
+- [Kestrel: Libuv transport marked as obsolete](#kestrel-libuv-transport-marked-as-obsolete)
 - [Localization: "Pubternal" APIs removed](#localization-pubternal-apis-removed)
 - [Localization: Obsolete constructor removed in request localization middleware](#localization-obsolete-constructor-removed-in-request-localization-middleware)
 - [Localization: ResourceManagerWithCultureStringLocalizer class and WithCulture interface member removed](#localization-resourcemanagerwithculturestringlocalizer-class-and-withculture-interface-member-removed)
@@ -79,6 +80,10 @@ If you're migrating from version 3.1 of .NET Core, ASP.NET Core, or EF Core to v
 
 ***
 
+[!INCLUDE[Kestrel: Libuv transport marked as obsolete](~/includes/core-changes/aspnetcore/5.0/kestrel-libuv-transport-obsolete.md)]
+
+***
+
 [!INCLUDE[Localization: "Pubternal" APIs removed](~/includes/core-changes/aspnetcore/5.0/localization-pubternal-apis-removed.md)]
 
 ***

docs/core/compatibility/aspnetcore.md

@@ -2,7 +2,7 @@
 title: ASP.NET Core breaking changes
 titleSuffix: ""
 description: Lists the breaking changes in ASP.NET Core.
-ms.date: 07/15/2020
+ms.date: 07/17/2020
 author: scottaddie
 ms.author: scaddie
 ---
@@ -54,6 +54,7 @@ The following breaking changes are documented on this page:
 - [Kestrel: Default supported TLS protocol versions changed](#kestrel-default-supported-tls-protocol-versions-changed)
 - [Kestrel: Empty HTTPS assembly removed](#kestrel-empty-https-assembly-removed)
 - [Kestrel: HTTP/2 disabled over TLS on incompatible Windows versions](#kestrel-http2-disabled-over-tls-on-incompatible-windows-versions)
+- [Kestrel: Libuv transport marked as obsolete](#kestrel-libuv-transport-marked-as-obsolete)
 - [Kestrel: Request trailer headers moved to new collection](#kestrel-request-trailer-headers-moved-to-new-collection)
 - [Kestrel: Transport abstraction layer changes](#kestrel-transport-abstractions-removed-and-made-public)
 - [Localization: APIs marked obsolete](#localization-resourcemanagerwithculturestringlocalizer-and-withculture-marked-obsolete)
@@ -134,6 +135,10 @@ The following breaking changes are documented on this page:
 
 ***
 
+[!INCLUDE[Kestrel: Libuv transport marked as obsolete](~/includes/core-changes/aspnetcore/5.0/kestrel-libuv-transport-obsolete.md)]
+
+***
+
 [!INCLUDE[Localization: "Pubternal" APIs removed](~/includes/core-changes/aspnetcore/5.0/localization-pubternal-apis-removed.md)]
 
 ***

includes/core-changes/aspnetcore/5.0/kestrel-libuv-transport-obsolete.md

@@ -0,0 +1,59 @@
+### Kestrel: Libuv transport marked as obsolete
+
+Earlier versions of ASP.NET Core used Libuv as an implementation detail of how asynchronous input and output was performed. In ASP.NET Core 2.0, an alternative, <xref:System.Net.Sockets.Socket>-based transport was developed. In ASP.NET Core 2.1, Kestrel switched to using the `Socket`-based transport by default. Libuv support was maintained for compatibility reasons.
+
+At this point, use of the `Socket`-based transport is far more common than the Libuv transport. Consequently, Libuv support is marked as obsolete in .NET 5.0 and will be removed entirely in .NET 6.0.
+
+As part of this change, Libuv support for new operating system platforms (like Windows ARM64) won't be added in the .NET 5.0 timeframe.
+
+For discussion on blocking issues that require the use of the Libuv transport, see the GitHub issue at [dotnet/aspnetcore#23409](https://github.com/dotnet/aspnetcore/issues/23409).
+
+#### Version introduced
+
+5.0 Preview 8
+
+#### Old behavior
+
+The Libuv APIs aren't marked as obsolete.
+
+#### New behavior
+
+The Libuv APIs are marked as obsolete.
+
+#### Reason for change
+
+The `Socket`-based transport is the default. There aren't any compelling reasons to continue using the Libuv transport.
+
+#### Recommended action
+
+Discontinue use of the [Libuv package](https://www.nuget.org/packages/Libuv) and extension methods.
+
+#### Category
+
+ASP.NET Core
+
+#### Affected APIs
+
+- [WebHostBuilderLibuvExtensions](/dotnet/api/microsoft.aspnetcore.hosting.webhostbuilderlibuvextensions?view=aspnetcore-3.0)
+- [WebHostBuilderLibuvExtensions.UseLibuv](/dotnet/api/microsoft.aspnetcore.hosting.webhostbuilderlibuvextensions.uselibuv?view=aspnetcore-3.0)
+- [Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv.LibuvTransportOptions](/dotnet/api/microsoft.aspnetcore.server.kestrel.transport.libuv.libuvtransportoptions?view=aspnetcore-3.0)
+- [Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv.LibuvTransportOptions.ThreadCount](/dotnet/api/microsoft.aspnetcore.server.kestrel.transport.libuv.libuvtransportoptions.threadcount?view=aspnetcore-3.0)
+- [Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv.LibuvTransportOptions.NoDelay](/dotnet/api/microsoft.aspnetcore.server.kestrel.transport.libuv.libuvtransportoptions.nodelay?view=aspnetcore-3.0)
+- [Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv.LibuvTransportOptions.MaxWriteBufferSize](/dotnet/api/microsoft.aspnetcore.server.kestrel.transport.libuv.libuvtransportoptions.maxwritebuffersize?view=aspnetcore-3.0)
+- [Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv.LibuvTransportOptions.MaxReadBufferSize](/dotnet/api/microsoft.aspnetcore.server.kestrel.transport.libuv.libuvtransportoptions.maxreadbuffersize?view=aspnetcore-3.0)
+- `Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv.LibuvTransportOptions.Backlog`
+
+<!-- 
+
+#### Affected APIs
+
+- `T:Microsoft.AspNetCore.Hosting.WebHostBuilderLibuvExtensions`
+- `Overload:Microsoft.AspNetCore.Hosting.WebHostBuilderLibuvExtensions.UseLibuv`
+- `T:Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv.LibuvTransportOptions`
+- `P:Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv.LibuvTransportOptions.ThreadCount`
+- `P:Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv.LibuvTransportOptions.NoDelay`
+- `P:Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv.LibuvTransportOptions.MaxWriteBufferSize`
+- `P:Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv.LibuvTransportOptions.MaxReadBufferSize`
+- `P:Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv.LibuvTransportOptions.Backlog`
+
+-->