Add package readme for obsolete .NET Standard 1.x packages

[MSDN-WhiteKnight]

There're a lot of .NET Standard 1.x packages that are no longer updated and just forward to inbox implementation both on .NET and .NET Framework (System.Runtime, System.Runtime.Extensions, System.Net.Http and others). They still show up high in NuGet search results, because they have lots of downloads, which creates some confusion for users.

This PR adds text for a generic package readme for these packages, to clarify that they should not be used. This readme should be added manually to them using NuGet gallery website. It can't be added automatically, because these packages are not published any more.

Fixes #86667

Related to #59630

[ghost]

Tagging subscribers to this area: @dotnet/ncl
See info in area-owners.md if you want to be subscribed.

Issue Details

---

The System.Net.Http package is not published since 2018, but it still shows up high in NuGet search results, because it has lots of downloads. This PR tries to clarify that it should not be explicitly referenced in user projects.

NOTE: When this is merged, the readme should be updated manually on NuGet gallery website. It will not be updated automatically, because the package is not published any more.

Fixes #86667

Related to #59630

Author:	MSDN-WhiteKnight
Assignees:	-
Labels:	area-System.Net.Http
Milestone:	-

[karelz]

I didn't realize we can edit README on the package in the nuget UI. Once we agree on the text, I can update it.

[karelz]

@dotnet/ncl can somebody else please check the text? (I heavily edited it, so I'd like to see one more opinion)

[karelz]

Thanks @MSDN-WhiteKnight for initiating it!

[jkotas]

The same guidance applies to all abandoned .NET Standard 1.x era packages: System.Runtime, System.Runtime.Extensions, ... . The exact story for each may differ a bit, but the end result is the same: These packages are obsolete and not necessary, and they should not be used.

Should we stamp the same readme on all these packages?

[MSDN-WhiteKnight]

The same guidance applies to all abandoned .NET Standard 1.x era packages: System.Runtime, System.Runtime.Extensions, ... . The exact story for each may differ a bit, but the end result is the same: These packages are obsolete and not necessary, and they should not be used.

Should we stamp the same readme on all these packages?

Likely yes. I've picked System.Net.Http first, because NuGet team mentioned it as a highly downloaded package without Readme (a second time already), but looks like there are more packages that are similar. Are all .NET Standard 1.x dependencies of NETStandard.Library obsolete?

If there're a lot of packages obsolete for the same reason, we probably don't need to add the same package.md file for every library. Instead we could add a single generic "obsolete-package-readme.md" somewhere under docs directory, then file issue to manually add it for packages that need it. Should i change this PR to add generic readme, or keep it focused for System.Net.Http for now?

[jkotas]

Should i change this PR to add generic readme, or keep it focused for System.Net.Http for now?

Generic readme makes more sense to me.

[MSDN-WhiteKnight]

Changed PR to add generic Readme in project docs directory. It now needs to be moved to area-Infrastructure or area-Meta.

[jkotas]

The text looks good to me.

@karelz @ericstj Could you please take it from here and apply this readme to all obsolete .NET Standard 1.x packages on github?

[ericstj]

We should gather the list of packages to apply this to and review it before taking action. Do we have that anywhere?

Here's a similar list I had from a previous effort where we looked at all packages that folks should remove on the latest framework. Probably this covers a lot - but some are not obsolete on older frameworks. https://gist.github.com/ericstj/de25740692bcbc7ee138f41956b2ea75

[MSDN-WhiteKnight]

I was thinking that the list of packages is equivalent to the list of .NET Standard 1.x dependencies of NETStandard.Library, but looks like it does not cover all obsolete packages. For example, System.Net.Http.Rtc is clearly obsolete, but it is not in .NET Standard. Where this package comes from? There's no directory under libraries for it now. Is it in the same bucket as .NET Standard packages, or it's obsolete for another reason?

Also, probably the best way to gather list of obsolete packages is to pick ones that NuGet forwards to inbox implementations on .NET Core and .NET Framework. Do someone know where's the forwarding logic in NuGet or SDK source code?

[karelz]

@ericstj who can help with generating and verify the list of packages?

[ghost]

Tagging subscribers to this area: @dotnet/area-meta
See info in area-owners.md if you want to be subscribed.

Issue Details

---

There're a lot of .NET Standard 1.x packages that are no longer updated and just forward to inbox implementation both on .NET and .NET Framework (System.Runtime, System.Runtime.Extensions, System.Net.Http and others). They still show up high in NuGet search results, because they have lots of downloads, which creates some confusion for users.

This PR adds text for a generic package readme for these packages, to clarify that they should not be used. This readme should be added manually to them using NuGet gallery website. It can't be added automatically, because these packages are not published any more.

Fixes #86667

Related to #59630

Author:	MSDN-WhiteKnight
Assignees:	karelz
Labels:	area-Meta, community-contribution
Milestone:	8.0.0

[ericstj]

@ViktorHofer would be good to help with this - I think we already have a similar list we produced for the upgrade assistant. I'd like us to go over that and decide what we do for each of these packages. In some cases it might make sense to actually obsolete them, rather than just add the readme saying they are obsolete.

[MSDN-WhiteKnight]

In some cases it might make sense to actually obsolete them, rather than just add the readme saying they are obsolete.

Maybe, actual .NET Standard 1.x packages can't be deprecated based on this: #86667 (comment) , but many non-.NET Standard ones probably can.

I'll post my current attempt at classifying obsolete packages:

.NET Standard 1.x packages (candidates for adding obsolete readme)

Microsoft.Win32.Primitives
System.AppContext
System.Collections
System.Collections.Concurrent
System.Console
System.Diagnostics.Debug
System.Diagnostics.Tools
System.Diagnostics.Tracing
System.Globalization
System.Globalization.Calendars
System.IO
System.IO.Compression
System.IO.Compression.ZipFile
System.IO.FileSystem
System.IO.FileSystem.Primitives
System.Linq
System.Linq.Expressions
System.Net.Http
System.Net.Primitives
System.Net.Sockets
System.ObjectModel
System.Reflection
System.Reflection.Extensions
System.Reflection.Primitives
System.Resources.ResourceManager
System.Runtime
System.Runtime.Extensions
System.Runtime.Handles
System.Runtime.InteropServices
System.Runtime.InteropServices.RuntimeInformation
System.Runtime.Numerics
System.Security.Cryptography.Algorithms
System.Security.Cryptography.Encoding
System.Security.Cryptography.Primitives
System.Security.Cryptography.X509Certificates
System.Text.Encoding
System.Text.Encoding.Extensions
System.Text.RegularExpressions
System.Threading
System.Threading.Tasks
System.Threading.Timer
System.Xml.ReaderWriter
System.Xml.XDocument

Other obsolete packages (candidates for deprecation)

Microsoft.CSharp
Microsoft.NETCore.Targets //already deprecated
Microsoft.VisualBasic
Microsoft.Win32.Registry
Microsoft.Windows.Compatibility.Shims
System.Collections.NonGeneric
System.Collections.Specialized
System.ComponentModel
System.ComponentModel.Annotations
System.ComponentModel.EventBasedAsync
System.ComponentModel.Primitives
System.ComponentModel.TypeConverter
System.Data.Common
System.Data.DataSetExtensions
System.Diagnostics.Contracts
System.Diagnostics.FileVersionInfo
System.Diagnostics.Process
System.Diagnostics.StackTrace
System.Diagnostics.TextWriterTraceListener
System.Diagnostics.TraceSource
System.Drawing.Primitives
System.Dynamic.Runtime
System.Globalization.Extensions
System.IO.FileSystem.AccessControl //already deprecated
System.IO.FileSystem.DriveInfo
System.IO.FileSystem.Watcher
System.IO.IsolatedStorage
System.IO.MemoryMappedFiles
System.IO.Pipes
System.IO.Pipes.AccessControl //already deprecated
System.IO.UnmanagedMemoryStream
System.Json
System.Linq.Parallel
System.Linq.Queryable
System.Net.Http.Rtc
System.Net.NameResolution
System.Net.NetworkInformation
System.Net.Ping
System.Net.Requests
System.Net.Security
System.Net.WebHeaderCollection
System.Net.WebSockets
System.Net.WebSockets.Client
System.Net.WebSockets.WebSocketProtocol
System.Numerics.Vectors.WindowsRuntime
System.Reflection.DispatchProxy
System.Reflection.Emit
System.Reflection.Emit.ILGeneration
System.Reflection.Emit.Lightweight
System.Reflection.TypeExtensions
System.Resources.Reader
System.Resources.Writer
System.Runtime.CompilerServices.VisualC
System.Runtime.InteropServices.WindowsRuntime
System.Runtime.Serialization.Formatters
System.Runtime.Serialization.Json
System.Runtime.Serialization.Primitives
System.Runtime.Serialization.Xml
System.Security.Claims
System.Security.Principal
System.Security.Principal.Windows
System.Security.SecureString
System.Threading.Overlapped
System.Threading.Tasks.Parallel
System.Threading.Thread
System.Threading.ThreadPool
System.Xml.XmlDocument
System.Xml.XmlSerializer
System.Xml.XPath
System.Xml.XPath.XDocument
System.Xml.XPath.XmlDocument

Non-obsolete packages (still have uses on .NET Framework - these should not be touched as part of this PR)

Microsoft.Bcl.AsyncInterfaces
Microsoft.Bcl.Cryptography
Microsoft.Bcl.HashCode
Microsoft.Diagnostics.Tracing.EventSource.Redist
Microsoft.IO.Redist
Microsoft.NETCore.Platforms.Future
NETStandard.Library
System.Buffers
System.Memory
System.Numerics.Vectors
System.Runtime.CompilerServices.Unsafe
System.Runtime.Experimental
System.Runtime.Intrinsics.Experimental
System.Runtime.Loader
System.Security.AccessControl
System.Security.Cryptography.Cng
System.Security.Cryptography.Csp
System.Security.Cryptography.OpenSsl
System.Threading.Tasks.Extensions
System.ValueTuple

[ViktorHofer]

Thanks for the contribution @MSDN-WhiteKnight. I'm not sure we want to check that README in for the cases where we would just need to update the metadata on nuget.org. I.e. I would just keep this saved somewhere, i.e. as a gist and retrieve it from there when necessary.

Note that while we have made some decent progress on package READMEs for active packages, we haven't yet started with obsoleting netstandard1.x packages and/or updating the ones that don't ship anymore from the main branch. We will revisit this topic when time allows.

[MSDN-WhiteKnight]

I'm not sure we want to check that README in for the cases where we would just need to update the metadata on nuget.org. I.e. I would just keep this saved somewhere, i.e. as a gist and retrieve it from there when necessary.

Yes, this PR is not required to be checked in, the purpose was to share the proposed readme text for review. Feel free to close and move to gist if that works better.

[ViktorHofer]

Sounds good. I'm closing this until we find time to deprecate the older .NET Standard 1.x packages.