Add readmes to reflection

CONTRIBUTING.md

@@ -61,20 +61,21 @@ The best way to create a minimal reproduction is gradually removing code and dep
 
 Project maintainers will merge changes that improve the product significantly and broadly align with the [.NET Roadmap](https://github.com/dotnet/core/blob/master/roadmap.md).
 
-Maintainers will not merge changes that have narrowly-defined benefits, due to compatibility risk. The .NET Core codebase is used by several Microsoft products (for example, ASP.NET Core, .NET Framework 4.x, Windows Universal Apps) to enable execution of managed code. Other companies are building products on top of .NET, too. We may revert changes if they are found to be breaking.
+Maintainers will not merge changes that have narrowly-defined benefits, due to compatibility risk. The .NET codebase is used by several Microsoft products (for example, ASP.NET Core, .NET Framework 4.x, Windows Universal Apps) to enable execution of managed code. Other companies are building products on top of .NET, too. We may revert changes if they are found to be breaking.
 
 Contributions must also satisfy the other published guidelines defined in this document as well as in [pr-guide docs](docs/pr-guide.md).
 
 ### DOs and DON'Ts
 
 Please do:
 
-* **DO** follow our [coding style](docs/coding-guidelines/coding-style.md) (C# code-specific)
+* **DO** follow our [coding style](docs/coding-guidelines/coding-style.md) (C# code-specific).
 * **DO** give priority to the current style of the project or file you're changing even if it diverges from the general guidelines.
 * **DO** include tests when adding new features. When fixing bugs, start with
   adding a test that highlights how the current behavior is broken.
 * **DO** keep the discussions focused. When a new or related topic comes up
   it's often better to create new issue than to side track the discussion.
+* **DO** clearly state on an issue that you are going to take on implementing it.
 * **DO** blog and tweet (or whatever) about your contributions, frequently!
 
 Please do not:
@@ -83,7 +84,7 @@ Please do not:
 * **DON'T** surprise us with big pull requests. Instead, file an issue and start
   a discussion so we can agree on a direction before you invest a large amount
   of time.
-* **DON'T** commit code that you didn't write. If you find code that you think is a good fit to add to .NET Core, file an issue and start a discussion before proceeding.
+* **DON'T** commit code that you didn't write. If you find code that you think is a good fit to add to .NET, file an issue and start a discussion before proceeding.
 * **DON'T** submit PRs that alter licensing related files or headers. If you believe there's a problem with them, file an issue and we'll be happy to discuss it.
 * **DON'T** add API additions without filing an issue and discussing with us first. See [API Review Process](docs/project/api-review-process.md).
 
@@ -154,7 +155,7 @@ You don't have to do this up-front. You can simply clone, fork, and submit your
 
 ### File Headers
 
-The following file header is the used for .NET Core. Please use it for new files.
+The following file header is the used for .NET. Please use it for new files.
 
 ```
 // Licensed to the .NET Foundation under one or more agreements.
@@ -201,7 +202,7 @@ Ports have a weaker contribution bar, at least initially. A functionally correct
 
 #### Copying Files from Other Projects
 
-.NET Core uses some files from other projects, typically where a binary distribution does not exist or would be inconvenient.
+.NET uses some files from other projects, typically where a binary distribution does not exist or would be inconvenient.
 
 The following rules must be followed for PRs that include files from another project:
 
@@ -213,6 +214,6 @@ See [IdnMapping.cs](./src/libraries/System.Private.CoreLib/src/System/Globalizat
 
 #### Porting Files from Other Projects
 
-There are many good algorithms implemented in other languages that would benefit the .NET Core project. The rules for porting a Java file to C#, for example, are the same as would be used for copying the same file, as described above.
+There are many good algorithms implemented in other languages that would benefit the .NET project. The rules for porting a Java file to C#, for example, are the same as would be used for copying the same file, as described above.
 
 [Clean-room](https://en.wikipedia.org/wiki/Clean_room_design) implementations of existing algorithms that are not permissively licensed will generally not be accepted. If you want to create or nominate such an implementation, please create an issue to discuss the idea.

src/libraries/README.md

@@ -0,0 +1,26 @@
+# .NET Libraries
+
+This folder contains the source and tests for the .NET Libraries. Different libraries are owned by different team members; refer to the [Areas](../../docs/area-owners.md#areas) list for lead and owner information.
+
+## Development Statuses
+
+Some libraries are under more active development than others. Depending on the library's status, expectations for issues and pull requests can vary. Check the library's folder for a `README.md` that declares the status for that library. Regardless of a library's status, refer to the [DOs and DON'Ts](../../CONTRIBUTING.md#dos-and-donts) and [Suggested Workflow](../../CONTRIBUTING.md#suggested-workflow) in our contribution guidelines before submitting a pull request.
+
+- **Active**
+  - Under active development by the team
+  - Issues will be considered for fix or addition to the backlog
+  - PRs for both features and fixes will be considered when aligned with current efforts
+- **Inactive**
+  - Under minimal development; quality is maintained
+  - Issues will be considered for fix or addition to the backlog
+  - PRs for both features and fixes will be considered
+- **Legacy**
+  - Not under development; maintained for compatibility
+  - Issues are likely to be closed without fixes
+  - PRs are unlikely to be accepted
+
+## Deployment
+
+Some libraries are included in the .NET SDK as part of the runtime's [shared framework](https://learn.microsoft.com/en-us/dotnet/standard/glossary#shared-framework). Other libraries are deployed as out-of-band (OOB) NuGet packages and need to be installed separately.
+
+For more information, see the [Runtime libraries overview](https://learn.microsoft.com/en-us/dotnet/standard/runtime-libraries-overview).

src/libraries/System.Reflection.Context/README.md

@@ -0,0 +1,9 @@
+# System.Reflection.Context
+Used by `System.ComponentModel` to support [`CustomReflectionContext`](https://learn.microsoft.com/dotnet/api/system.reflection.context.customreflectioncontext).
+
+Documentation can be found at https://learn.microsoft.com/dotnet/api/system.reflection.context.
+
+## Status: [Legacy](../../libraries/README.md#development-statuses)
+
+## Deployment
+[System.Reflection.Context](https://www.nuget.org/packages/System.Reflection.Context) NuGet package

src/libraries/System.Reflection.DispatchProxy/README.md

@@ -0,0 +1,10 @@
+# System.Reflection.DispatchProxy
+Supports the [`DispatchProxy`](https://learn.microsoft.com/dotnet/api/system.reflection.dispatchproxy) class which is used to forward methods to another class.
+
+Documentation can be found at https://learn.microsoft.com/dotnet/api/system.reflection.dispatchproxy.
+
+## Status: [Legacy](../../libraries/README.md#development-statuses)
+Although used for key scenarios by the community, it has remained relatively unchanged. Internally it uses [Emit](../System.Reflection.Emit/README.md) to generate the proxies so it doesn't work on all platforms.
+
+## Deployment
+[System.Reflection.DispatchProxy](https://www.nuget.org/packages/System.Reflection.DispatchProxy) NuGet package

src/libraries/System.Reflection.Emit.ILGeneration/README.md

@@ -0,0 +1,9 @@
+# System.Reflection.Emit.ILGeneration
+Contains types used with [`System.Reflection.Emit`](../System.Reflection.Emit/README.md).
+
+The primary class is [`ILGenerator`](https://learn.microsoft.com/dotnet/api/system.reflection.emit.ilgenerator).
+
+## Status: [Inactive](../../libraries/README.md#development-statuses)
+
+## Deployment
+[System.Reflection.Emit.ILGeneration](https://www.nuget.org/packages/System.Reflection.Emit.ILGeneration) is included in the shared framework.

src/libraries/System.Reflection.Emit.Lightweight/README.md

@@ -0,0 +1,10 @@
+# System.Reflection.Emit.Lightweight
+The primary class is [`DynamicMethod`](https://learn.microsoft.com/dotnet/api/system.reflection.emit.DynamicMethod).
+
+## Status: [Inactive](../../libraries/README.md#development-statuses)
+
+## Deployment
+[System.Reflection.Emit.Lightweight](https://www.nuget.org/packages/System.Reflection.Emit.Lightweight) is included in the shared framework.
+
+## See also
+[`System.Reflection.Emit`](../System.Reflection.Emit/README.md)

src/libraries/System.Reflection.Emit/README.md

@@ -0,0 +1,22 @@
+# System.Reflection.Emit
+Supports generating code dynamically and then running it in-memory. This is used to generate types dynamically which are commonly used to generate proxies and other dynamic classes that may not be known ahead-of-time (in which case C# generation could be used, for example). It is also used to invoke members more efficiently than the [`standard runtime invoke mechanism`](https://learn.microsoft.com/dotnet/api/system.reflection.methodbase.invoke). However, starting in 7.0, most IL generation is now done automatically so the need to manually generate IL for performance is reduced.
+
+Not all platforms and runtimes support IL.Emit.
+
+Documentation can be found at https://learn.microsoft.com/dotnet/api/system.reflection.emit. The primary class is [`AssemblyBuilder`](https://learn.microsoft.com/dotnet/api/system.reflection.emit.AssemblyBuilder).
+
+## Status: [Inactive](../../libraries/README.md#development-statuses)
+The APIs and functionality are mature, but do get extended occasionally.
+
+## Deployment
+[System.Reflection.Emit](https://www.nuget.org/packages/System.Reflection.Emit) is included in the shared framework.
+
+## Source
+
+* CoreClr-specific: [../../coreclr/System.Private.CoreLib/src/System/Reflection/Emit](../../coreclr/System.Private.CoreLib/src/System/Reflection/Emit)
+* Mono-specific: [../../mono/System.Private.CoreLib/src/System/Reflection/Emit](../../mono/System.Private.CoreLib/src/System/Reflection/Emit)
+* Shared between CoreClr and Mono: [../System.Private.CoreLib/src/System/Reflection/Emit](../System.Private.CoreLib/src/System/Reflection/Emit)
+
+## See also
+- [`System.Reflection.Emit.Lightweight`](../System.Reflection.Emit.Lightweight/README.md)
+- [`System.Reflection.Emit.ILGeneration`](../System.Reflection.Emit.ILGeneration/README.md)

src/libraries/System.Reflection.Extensions/README.md

@@ -0,0 +1,7 @@
+# System.Reflection.Extensions
+This supports forwarding types to the runtime including [CustomAttributeExtensions](https://learn.microsoft.com/dotnet/api/system.reflection.CustomAttributeExtensions), [InterfaceMapping](https://learn.microsoft.com/dotnet/api/system.reflection.InterfaceMapping) and [RuntimeReflectionExtensions](https://learn.microsoft.com/dotnet/api/system.reflection.RuntimeReflectionExtensions).
+
+## Status: [Legacy](../../libraries/README.md#development-statuses)
+
+## Deployment
+[System.Reflection.Extensions](https://www.nuget.org/packages/System.Reflection.Extensions) is included in the shared framework.

src/libraries/System.Reflection.Metadata/README.md

@@ -0,0 +1,10 @@
+# System.Reflection.Metadata
+This provides a low-level API for inspecting and writing raw assembly contents according to ECMA-335. Assemblies and types are not loaded into the current runtime context.
+
+The primary classes are [MetadataReader](https://learn.microsoft.com/dotnet/api/system.reflection.metadata.metadatareader) and [MetadataBuilder](https://learn.microsoft.com/dotnet/api/system.reflection.metadata.ecma335.metadatabuilder). Documentation can be found at https://learn.microsoft.com/dotnet/api/system.reflection.metadata and https://learn.microsoft.com/dotnet/api/system.reflection.metadata.ecma335.
+
+## Status: [Inactive](../../libraries/README.md#development-statuses)
+The APIs and functionality are mature, but do get extended occasionally.
+
+## Deployment
+[System.Reflection.Metadata](https://www.nuget.org/packages/System.Reflection.Metadata) is included in the shared framework.

src/libraries/System.Reflection.Metadata/src/README.md

@@ -2,7 +2,7 @@
 
 This package provides a low-level .NET (ECMA-335) metadata reader and writer. It's geared for performance and is the ideal choice for building higher-level libraries that intend to provide their own object model, such as compilers. The metadata format is defined by the [ECMA-335 - Common Language Infrastructure (CLI)](http://www.ecma-international.org/publications/standards/Ecma-335.htm) specification and [its amendments](https://github.com/dotnet/runtime/blob/main/docs/design/specs/Ecma-335-Augments.md).
 
-The `System.Reflection.Metadata` library is built-in as part of the shared framework in .NET Runtime. The package can be installed when you need to use it in other target frameworks.
+The `System.Reflection.Metadata` library is included in the .NET Runtime shared framework. The package can be installed when you need to use it in other target frameworks.
 
 For more information, see the documentation:
 

src/libraries/System.Reflection.MetadataLoadContext/README.md

@@ -0,0 +1,14 @@
+# System.Reflection.MetadataLoadContext
+This provides a high-level API for inspecting types given raw assembly contents according to ECMA-335. The types from a provided assembly are loaded into a[`MetadataLoadContext`](https://learn.microsoft.com/dotnet/api/system.reflection.metadataloadcontext) instance which returns `System.Type`, `System.MemberInfo`, etc. However, these reflection types do not support invocation and they are different instances from the types returned from runtime introspection. Because of this, this allows any assembly to be read, even if it's for a different platform provided that all assembly references are accounted for.<br/>
+
+This library takes a dependency on `System.Reflection.Metadata` for reading the assembly.
+
+## Status: [Inactive](../system.reflection/overview.md#status)
+The APIs and functionality are mature, but do get extended occasionally.
+
+## Source
+
+* [../System.Reflection.Metadata](../System.Reflection.Metadata)
+
+## Deployment
+[System.Reflection.MetadataLoadContext](https://www.nuget.org/packages/System.Reflection.MetadataLoadContext) NuGet package.

src/libraries/System.Reflection.Primitives/README.md

@@ -0,0 +1,7 @@
+# System.Reflection.Primitives
+Contains reflection types such as [TypeAttributes](https://learn.microsoft.com/dotnet/api/system.reflection.typeattributes). Some of these types are forwarded to the runtime. In the future, the non-forwarded types may be lifted to the runtime and then type forwards added.
+
+## Status: [Legacy](../../libraries/README.md#development-statuses)
+
+## Deployment
+[System.Reflection.Primitives](https://www.nuget.org/packages/System.Reflection.Primitives) is included in the shared framework.

src/libraries/System.Reflection.TypeExtensions/README.md

@@ -0,0 +1,7 @@
+# System.Reflection.TypeExtensions
+This is a facade assembly that has extension methods for common reflection types. It was used in the past to expose common functionality across different runtimes in a uniform way.
+
+## Status: [Legacy](../../libraries/README.md#development-statuses)
+
+## Deployment
+[System.Reflection.TypeExtensions](https://www.nuget.org/packages/System.Reflection.TypeExtensions) is included in the shared framework.

src/libraries/System.Reflection/README.md

@@ -0,0 +1,16 @@
+# System.Reflection
+This is the primary reflection assembly. It is used for late-bound introspection and invocation of types that are loaded into the currently executing "runtime context". This introspection is exposed by various reflection types including [`Assembly`](https://learn.microsoft.com/dotnet/api/system.reflection.assembly), [`Type`](https://learn.microsoft.com/dotnet/api/system.type), [`ConstructorInfo`](https://learn.microsoft.com/dotnet/api/system.reflection.constructorinfo), [`MethodInfo`](https://learn.microsoft.com/dotnet/api/system.reflection.methodinfo) and [`FieldInfo`](https://learn.microsoft.com/dotnet/api/system.reflection.fieldinfo). The primary mechanism to invoking members in a late-bound manner is through [`MethodBase.Invoke`](https://learn.microsoft.com/dotnet/api/system.reflection.methodbase.invoke).
+
+Documentation can be found at https://learn.microsoft.com/dotnet/api/system.reflection.
+
+## Status: [Active](../../libraries/README.md#development-statuses)
+Although these common types are mature, the code base continues to evolve for better performance and to keep up with language and runtime enhancements such as byref-like types.
+
+## Source
+
+* CoreClr-specific: [../../coreclr/System.Private.CoreLib/src/System/Reflection](../../coreclr/System.Private.CoreLib/src/System/Reflection)
+* Mono-specific: [../../mono/System.Private.CoreLib/src/System/Reflection](../../mono/System.Private.CoreLib/src/System/Reflection)
+* Shared between CoreClr and Mono: [../System.Private.CoreLib/src/System/Reflection](../System.Private.CoreLib/src/System/Reflection)
+
+## Deployment
+[System.Relection](https://www.nuget.org/packages/System.Reflection) is included in the shared framework.