Add package readmes (#43)

* Add assembly readmes. * Initialize package readme files. * Add CODEOWNERS file * Fix XmlDocumentXPathExtensions * Remove source build from CODEOWNERS Co-authored-by: Viktor Hofer <[email protected]> * Centralize bug bar and deployment. Delete assembly readme.md files. * Delete the rest for sure. * Apply feedback to replace contributing line with only the license. * Fine tune System.Json * Update WebSocketProtocol readme * Update DispatchProxy * Update PACKAGE.md with package description and links * Update PACKAGE.md for System.Buffers * Update PACKAGE.md for System.Memory * Update PACKAGE.md for System.Numerics.Vectors * Update PACKAGE.md for System.Runtime.CompilerServices.Unsafe * Apply suggestions from code review --------- Co-authored-by: Viktor Hofer <[email protected]> Co-authored-by: Natalia Kondratyeva <[email protected]> Co-authored-by: Steve Harter <[email protected]> Co-authored-by: Stephen Toub <[email protected]> Co-authored-by: Tanner Gooding <[email protected]>
dotnet · Nov 8, 2024 · 381571f · 381571f
1 parent fba2ed2
commit 381571f
Show file tree

Hide file tree

Showing 14 changed files with 613 additions and 1 deletion.
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -0,0 +1,15 @@
+# Users referenced in this file will automatically be requested as reviewers for PRs that modify the given paths.
+# See https://help.github.com/articles/about-code-owners/
+
+/src/Microsoft.Bcl.HashCode                                                       @dotnet/area-system-runtime
+/src/Microsoft.IO.Redist                                                          @dotnet/area-system-io
+/src/System.Buffers                                                               @dotnet/area-system-buffers
+/src/System.Data.SqlClient                                                        @cheenamalhotra @david-engel
+/src/System.Json
+/src/System.Memory                                                                @dotnet/area-system-memory
+/src/System.Net.WebSockets.WebSocketProtocol                                      @dotnet/ncl
+/src/System.Numerics.Vectors                                                      @dotnet/area-system-numerics
+/src/System.Reflection.DispatchProxy                                              @dotnet/area-system-reflection
+/src/System.Runtime.CompilerServices.Unsafe                                       @dotnet/area-system-runtime-compilerservices
+/src/System.Threading.Tasks.Extensions                                            @dotnet/area-system-threading-tasks @stephentoub
+/src/System.Xml.XPath.XmlDocument                                                 @dotnet/area-system-xml
diff --git a/README.md b/README.md
@@ -19,6 +19,13 @@ Package versions produced by official builds for this repo will automatically co
 
 The default build will automatically build all of the libraries that have been added to the repo. That said, given this repository is used to service packages, and you won't always want to service all of the packages at the same time, packages for libraries are not generated by default. To enable a library to produce a package and be serviced, set the `<IsPackable>` property to `true` in the library's project file.
 
-## Contributing
+## Contribution bar
+
+- [We only consider fixes that unblock critical issues](https://github.com/dotnet/runtime/blob/main/src/libraries/README.md#primary-bar)
+- [We don't accept refactoring changes due to new language features](https://github.com/dotnet/runtime/blob/main/src/libraries/README.md#secondary-bars)
 
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
+
+## Deployment
+
+All the assemblies in this repository are shipped as NuGet packages.
diff --git a/src/Microsoft.Bcl.HashCode/src/PACKAGE.md b/src/Microsoft.Bcl.HashCode/src/PACKAGE.md
@@ -0,0 +1,243 @@
+## About
+
+Provides the HashCode type for .NET Standard 2.0. This package is not required starting with .NET Standard 2.1 and .NET Core 3.0.
+
+The HashCode type is shipped as part of the shared framework starting with .NET 5.
+
+## Key Features
+
+The HashCode type offered in this assembly combines the hash code for multiple values into a single hash code.
+
+## How to Use
+
+The static methods in this class combine the default hash codes of _up to eight_ values.
+
+```cs
+using System;
+using System.Collections.Generic;
+
+public struct OrderOrderLine : IEquatable<OrderOrderLine>
+{
+    public int OrderId { get; }
+    public int OrderLineId { get; }
+
+    public OrderOrderLine(int orderId, int orderLineId) => (OrderId, OrderLineId) = (orderId, orderLineId);
+
+    public override bool Equals(object obj) => obj is OrderOrderLine o && Equals(o);
+
+    public bool Equals(OrderOrderLine other) => OrderId == other.OrderId && OrderLineId == other.OrderLineId;
+
+    public override int GetHashCode() => HashCode.Combine(OrderId, OrderLineId);
+}
+
+class Program
+{
+    static void Main(string[] args)
+    {
+        var set = new HashSet<OrderOrderLine>
+        {
+            new OrderOrderLine(1, 1),
+            new OrderOrderLine(1, 1),
+            new OrderOrderLine(1, 2)
+        };
+
+        Console.WriteLine($"Item count: {set.Count}.");
+    }
+}
+// The example displays the following output:
+// Item count: 2.
+```
+
+The instance methods in this class combine the hash codes of _more than eight_ values.
+
+```cs
+using System;
+using System.Collections.Generic;
+
+public struct Path : IEquatable<Path>
+{
+    public IReadOnlyList<string> Segments { get; }
+
+    public Path(params string[] segments) => Segments = segments;
+
+    public override bool Equals(object obj) => obj is Path o && Equals(o);
+
+    public bool Equals(Path other)
+    {
+        if (ReferenceEquals(Segments, other.Segments)) return true;
+        if (Segments is null || other.Segments is null) return false;
+        if (Segments.Count != other.Segments.Count) return false;
+
+        for (var i = 0; i < Segments.Count; i++)
+        {
+            if (!string.Equals(Segments[i], other.Segments[i]))
+                return false;
+        }
+
+        return true;
+    }
+
+    public override int GetHashCode()
+    {
+        var hash = new HashCode();
+
+        for (var i = 0; i < Segments?.Count; i++)
+            hash.Add(Segments[i]);
+
+        return hash.ToHashCode();
+    }
+}
+
+class Program
+{
+    static void Main(string[] args)
+    {
+        var set = new HashSet<Path>
+        {
+            new Path("C:", "tmp", "file.txt"),
+            new Path("C:", "tmp", "file.txt"),
+            new Path("C:", "tmp", "file.tmp")
+        };
+
+        Console.WriteLine($"Item count: {set.Count}.");
+    }
+}
+// The example displays the following output:
+// Item count: 2.
+```
+
+The instance methods also combine the hash codes produced by a specific IEqualityComparer<T> implementation.
+
+```cs
+using System;
+using System.Collections.Generic;
+
+public struct Path : IEquatable<Path>
+{
+    public IReadOnlyList<string> Segments { get; }
+
+    public Path(params string[] segments) => Segments = segments;
+
+    public override bool Equals(object obj) => obj is Path o && Equals(o);
+
+    public bool Equals(Path other)
+    {
+        if (ReferenceEquals(Segments, other.Segments)) return true;
+        if (Segments is null || other.Segments is null) return false;
+        if (Segments.Count != other.Segments.Count) return false;
+
+        for (var i = 0; i < Segments.Count; i++)
+        {
+            if (!string.Equals(Segments[i], other.Segments[i], StringComparison.OrdinalIgnoreCase))
+                return false;
+        }
+
+        return true;
+    }
+
+    public override int GetHashCode()
+    {
+        var hash = new HashCode();
+
+        for (var i = 0; i < Segments?.Count; i++)
+            hash.Add(Segments[i], StringComparer.OrdinalIgnoreCase);
+
+        return hash.ToHashCode();
+    }
+}
+
+class Program
+{
+    static void Main(string[] args)
+    {
+        var set = new HashSet<Path>
+        {
+            new Path("C:", "tmp", "file.txt"),
+            new Path("C:", "TMP", "file.txt"),
+            new Path("C:", "tmp", "FILE.TXT")
+        };
+
+        Console.WriteLine($"Item count: {set.Count}.");
+    }
+}
+// The example displays the following output:
+// Item count: 1.
+```
+
+The HashCode structure must be passed by-reference to other methods, as it is a value type.
+```cs
+using System;
+using System.Collections.Generic;
+
+public struct Path : IEquatable<Path>
+{
+    public IReadOnlyList<string> Segments { get; }
+
+    public Path(params string[] segments) => Segments = segments;
+
+    public override bool Equals(object obj) => obj is Path o && Equals(o);
+
+    public bool Equals(Path other)
+    {
+        if (ReferenceEquals(Segments, other.Segments)) return true;
+        if (Segments is null || other.Segments is null) return false;
+        if (Segments.Count != other.Segments.Count) return false;
+
+        for (var i = 0; i < Segments.Count; i++)
+        {
+            if (!PlatformUtils.PathEquals(Segments[i], other.Segments[i]))
+                return false;
+        }
+
+        return true;
+    }
+
+    public override int GetHashCode()
+    {
+        var hash = new HashCode();
+
+        for (var i = 0; i < Segments?.Count; i++)
+            PlatformUtils.AddPath(ref hash, Segments[i]);
+
+        return hash.ToHashCode();
+    }
+}
+
+internal static class PlatformUtils
+{
+    public static bool PathEquals(string a, string b) => string.Equals(a, b, StringComparison.OrdinalIgnoreCase);
+    public static void AddPath(ref HashCode hash, string path) => hash.Add(path, StringComparer.OrdinalIgnoreCase);
+}
+
+class Program
+{
+    static void Main(string[] args)
+    {
+        var set = new HashSet<Path>
+        {
+            new Path("C:", "tmp", "file.txt"),
+            new Path("C:", "TMP", "file.txt"),
+            new Path("C:", "tmp", "FILE.TXT")
+        };
+
+        Console.WriteLine($"Item count: {set.Count}.");
+    }
+}
+// The example displays the following output:
+// Item count: 1.
+```
+
+## Main Types
+
+The main types provided by this library are:
+
+- System.HashCode
+
+## Additional Documentation
+
+- [Security design doc for System.HashCode](https://github.com/dotnet/runtime/tree/main/docs/design/security/System.HashCode.md)
+- API reference can be found in: https://learn.microsoft.com/en-us/dotnet/api/system.hashcode
+
+## License
+
+Microsoft.Bcl.HashCode is released as open source under the [MIT license](https://licenses.nuget.org/MIT).
diff --git a/src/Microsoft.IO.Redist/src/PACKAGE.md b/src/Microsoft.IO.Redist/src/PACKAGE.md
@@ -0,0 +1,26 @@
+## About
+
+Downlevel support package for System.IO classes.
+
+Regular users do not need to reference this package directly. Please use System.IO instead.
+
+## Main Types
+
+The main types provided by this library are:
+
+- Microsoft.IO.Directory
+- Microsoft.IO.DirectoryInfo
+- Microsoft.IO.EnumerationOptions
+- Microsoft.IO.File
+- Microsoft.IO.FileInfo
+- Microsoft.IO.FileSystemEnumerable
+- Microsoft.IO.FileSystemEnumerator
+- Microsoft.IO.FileSystemEntry
+
+## Additional Documentation
+
+- System.IO namespace: https://learn.microsoft.com/en-us/dotnet/api/system.io
+
+## License
+
+Microsoft.IO.Redist is released as open source under the [MIT license](https://licenses.nuget.org/MIT).
diff --git a/src/System.Buffers/src/PACKAGE.md b/src/System.Buffers/src/PACKAGE.md
@@ -0,0 +1,21 @@
+## About
+
+Provides resource pooling of any type for performance-critical applications that allocate and deallocate objects frequently.
+
+## Main Types
+
+The main types provided by this library are:
+
+- System.Buffers.ArrayPool<T>
+
+## Additional Documentation
+
+- API reference can be found in: https://learn.microsoft.com/en-us/dotnet/api/system.buffers
+
+## Related Packages
+
+ArrayPool is shipped as part of the shared framework starting with .NET Core 3.1.
+
+## License
+
+System.Buffers is released as open source under the [MIT license](https://licenses.nuget.org/MIT).
diff --git a/src/System.Data.SqlClient/src/PACKAGE.md b/src/System.Data.SqlClient/src/PACKAGE.md
@@ -0,0 +1,35 @@
+## About
+
+The legacy .NET Data Provider for SQL Server. These classes provide access to versions of SQL Server and encapsulate database-specific protocols, including tabular data stream (TDS).
+
+**System.Data.SqlClient is deprecated. Please use Microsoft.Data.SqlClient instead.**
+
+## Main Types
+
+The main types provided by this library are:
+
+- System.Data.SqlClient.SqlConnection
+- System.Data.SqlClient.SqlException
+- System.Data.SqlClient.SqlParameter
+- System.Data.SqlDbType
+- System.Data.SqlClient.SqlDataReader
+- System.Data.SqlClient.SqlCommand
+- System.Data.SqlClient.SqlTransaction
+- System.Data.SqlClient.SqlParameterCollection
+- System.Data.SqlClient.SqlClientFactory
+
+## Additional Documentation
+
+- [Introducing the new Microsoft.Data.SqlClient](https://devblogs.microsoft.com/dotnet/introducing-the-new-microsoftdatasqlclient/)
+- [https://techcommunity.microsoft.com/t5/sql-server-blog/announcement-system-data-sqlclient-package-is-now-deprecated/ba-p/4227205](Announcement: System.Data.SqlClient package is now deprecated)
+- For conceptual information about using this namespace when programming with .NET, see [SQL Server and ADO.NET](https://learn.microsoft.com/en-us/dotnet/framework/data/adonet/sql/).
+- API reference for System.Data.SqlClient can be found in: https://learn.microsoft.com/en-us/dotnet/api/system.data.sqlclient?view=netframework-4.8.1
+- API reference for Microsoft.Data.SqlClient can be found in: https://learn.microsoft.com/en-us/dotnet/api/microsoft.data.sqlclient
+
+## Related Packages
+
+- https://www.nuget.org/packages/Microsoft.Data.SqlClient
+
+## License
+
+System.Data.SqlClient is released as open source under the [MIT license](https://licenses.nuget.org/MIT).
diff --git a/src/System.Json/src/PACKAGE.md b/src/System.Json/src/PACKAGE.md
@@ -0,0 +1,29 @@
+## About
+
+Provides standards-based support for the serialization of JavaScript Object Notation (JSON).
+
+**The System.Json namespace was designed for Silverlight, which is no longer supported. For processing JSON, we recommend using APIs in the System.Text.Json namespace instead.**
+
+## Main Types
+
+The main types provided by this library are:
+
+- System.Json.JsonArray
+- System.Json.JsonObject
+- System.Json.JsonPrimitive
+- System.Json.JsonValue
+
+## Additional Documentation
+
+- API reference for System.Json can be found in: https://learn.microsoft.com/en-us/dotnet/api/system.json
+- API reference for System.Text.Json can be found in: https://learn.microsoft.com/en-us/dotnet/api/system.text.json
+- [JSON serialization and deserialization (marshalling and unmarshalling) in .NET - overview](https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/overview)
+- [System.Text.Json in .NET Blog](https://devblogs.microsoft.com/dotnet/tag/system-text-json/)
+
+## Related Packages
+
+- https://www.nuget.org/packages/System.Text.Json
+
+## License
+
+System.Json is released as open source under the [MIT license](https://licenses.nuget.org/MIT).