Merge branch 'main' into fix/docs-lazycs-summary-111921

Author: amritanand-py

.github/copilot-instructions.md

@@ -23,6 +23,7 @@ In addition to the rules enforced by `.editorconfig`, you SHOULD:
 - When running tests, if possible use filters and check test run counts, or look at test logs, to ensure they actually ran.
 - Do not finish work with any tests commented out or disabled that were not previously commented out or disabled.
 - When writing tests, do not emit "Act", "Arrange" or "Assert" comments.
+- For markdown (`.md`) files, ensure there is no trailing whitespace at the end of any line.
 
 ---
 

.github/workflows/backport.yml

@@ -46,7 +46,8 @@ jobs:
 
         **IMPORTANT**: If this backport is for a servicing release, please verify that:
 
-        - The PR target branch is `release/X.0-staging`, not `release/X.0`.
+        - For .NET 8 and .NET 9: The PR target branch is `release/X.0-staging`, not `release/X.0`.
+        - For .NET 10+: The PR target branch is `release/X.0` (no `-staging` suffix).
 
         ## Package authoring no longer needed in .NET 9
 

.github/workflows/jit-format.yml

@@ -15,7 +15,7 @@ jobs:
         os:
           - name: linux
             image: ubuntu-latest
-            container: mcr.microsoft.com/dotnet-buildtools/prereqs:azurelinux-3.0-net10.0-cross-amd64
+            container: mcr.microsoft.com/dotnet-buildtools/prereqs:azurelinux-3.0-net11.0-cross-amd64
             extension: '.sh'
             cross: '--cross'
             rootfs: '/crossrootfs/x64'

README.md

@@ -37,7 +37,7 @@ We welcome contributions! Many people all over the world have helped make this p
 
 ## Reporting security issues and security bugs
 
-Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) <secure@microsoft.com>. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the [Security TechCenter](https://www.microsoft.com/msrc/faqs-report-an-issue). You can also find these instructions in this repo's [Security doc](SECURITY.md).
+Security issues and bugs should be reported privately to the Microsoft Security Response Center (MSRC) via the [MSRC Researcher Portal](https://msrc.microsoft.com/report/vulnerability/new). You should receive a response within 24 hours. Further information can be found in the [Security TechCenter](https://www.microsoft.com/msrc/faqs-report-an-issue). You can also find these instructions in this repo's [Security doc](SECURITY.md).
 
 Also see info about related [Microsoft .NET Bounty Program](https://www.microsoft.com/msrc/bounty-dot-net-core).
 

SECURITY.md

@@ -6,9 +6,9 @@ The .NET Core and ASP.NET Core support policy, including supported versions can
 
 ## Reporting a Vulnerability
 
-Security issues and bugs should be reported privately to the Microsoft Security Response Center (MSRC), either by emailing [email protected] or via the portal at https://msrc.microsoft.com.
+Security issues and bugs should be reported privately to the Microsoft Security Response Center (MSRC), via the [MSRC Researcher Portal](https://msrc.microsoft.com/report/vulnerability/new).
 You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your
-original message. Further information, including the MSRC PGP key, can be found in the [MSRC Report an Issue FAQ](https://www.microsoft.com/en-us/msrc/faqs-report-an-issue).
+original message. Further information can be found in the [MSRC Report an Issue FAQ](https://www.microsoft.com/en-us/msrc/faqs-report-an-issue).
 
 Reports via MSRC may qualify for the .NET Core Bug Bounty. Details of the .NET Core Bug Bounty including terms and conditions are at [https://aka.ms/corebounty](https://aka.ms/corebounty).
 

docs/coding-guidelines/adding-api-guidelines.md

@@ -44,12 +44,27 @@ should be added to `net10.0`. [More Information on TargetFrameworks](https://lea
 
 New public APIs must be documented with triple-slash comments on top of them. Visual Studio automatically generates the structure for you when you type `///`.
 
+[API writing guidelines](https://github.com/dotnet/dotnet-api-docs/wiki) has information about language and proper style for writing API documentation.
 If your new API or the APIs it calls throw any exceptions, those need to be manually documented by adding the `<exception></exception>` elements.
 
-After your change is merged, we will eventually port them to the dotnet-api-docs repo, where we will review them for language and proper style (For more information, see the [API writing guidelines](https://github.com/dotnet/dotnet-api-docs/wiki)).
+After your change is merged, we will eventually port them to the [dotnet-api-docs](https://github.com/dotnet/dotnet-api-docs) repo. The tools used for this port live in [api-docs-sync](https://github.com/dotnet/api-docs-sync) repo. Once the dotnet-api-docs change
+is merged, your comments will start showing up in the official API documentation at https://learn.microsoft.com, and later they'll appear in IntelliSense
+in Visual Studio and Visual Studio Code.
 
-Once the dotnet-api-docs change is merged, your comments will start showing up in the official API documentation at https://learn.microsoft.com, and later they'll appear in IntelliSense in Visual Studio and Visual Studio Code.
-Once the documentation is official, any subsequent updates to it must be made directly in https://github.com/dotnet/dotnet-api-docs/. It's fine to make updates to the triple slash comments later, they just won't automatically flow into the official docs.
+The rest of the documentation workflow depends on whether the assembly has the `UseCompilerGeneratedDocXmlFile` property set in its project file:
+
+**For libraries without this property (or with it set to `true`, which is the default):**
+- Source comments in this repo are the source of truth for documentation.
+- Triple-slash comments in source code are synced to dotnet-api-docs periodically (every preview).
+- More recently introduced libraries typically follow this workflow.
+
+**For libraries with `<UseCompilerGeneratedDocXmlFile>false</UseCompilerGeneratedDocXmlFile>`:**
+- The [dotnet-api-docs](https://github.com/dotnet/dotnet-api-docs) repo is the source of truth for documentation.
+- Triple-slash comments in source code are synced to dotnet-api-docs **only once** for newly introduced APIs. After the initial sync, all subsequent documentation
+updates must be made directly in the dotnet-api-docs repo.
+- It's fine to make updates to the triple-slash comments later to aid local development, they just won't automatically flow into the official docs. Copilot can help with porting small changes
+in triple-slash comments to dotnet-api-docs. [PortToDocs](https://github.com/dotnet/api-docs-sync/blob/main/docs/PortToDocs.md) tool works better for ports of large changes.
+- Older libraries typically follow this workflow. Libraries in this mode can work towards a better workflow in the future by using api-docs-sync tools to port back docs to source, then removing the `UseCompilerGeneratedDocXmlFile` property.
 
 ## FAQ
 

docs/coding-guidelines/project-guidelines.md

@@ -192,7 +192,7 @@ The `UseCompilerGeneratedDocXmlFile` property controls how XML documentation fil
 </PropertyGroup>
 ```
 
-Setting `UseCompilerGeneratedDocXmlFile` to `false` is typically done for stable APIs where manually curated documentation exists that should be preferred over compiler-generated documentation.
+See the [Documentation](adding-api-guidelines.md#documentation) section in the API guidelines for more details about the documentation workflow.
 
 If a project sets this to `false` but the Microsoft.Private.Intellisense package doesn't have documentation for the assembly, a warning is shown suggesting to remove the property to let the compiler generate the file.
 

docs/design/coreclr/botr/readytorun-format.md

@@ -30,8 +30,8 @@ The COR header and ECMA 335 metadata pointed to by the COM descriptor data direc
 in the COFF header represent a full copy of the input IL and MSIL metadata it was generated from.
 
 **Composite R2R files** currently conform to Windows PE executable file format as the
-native envelope. Moving forward we plan to gradually add support for platform-native
-executable formats (ELF on Linux, MachO on OSX) as the native envelopes. There is a
+native envelope. Moving forward we [plan to gradually add support for platform-native
+executable formats](./readytorun-platform-native-envelope.md) (ELF on Linux, MachO on OSX) as the native envelopes. There is a
 global CLI / COR header in the file, but it only exists to facilitate pdb generation, and does
 not participate in any usages by the CoreCLR runtime. The ReadyToRun header structure is pointed to
 by the well-known export symbol `RTR_HEADER` and has the `READYTORUN_FLAG_COMPOSITE` flag set.

docs/design/coreclr/botr/readytorun-overview.md

@@ -60,7 +60,7 @@ Some of this information can be omitted or stored in more efficient form, e.g.:
 - The garbage collection information can be omitted for environments with conservative garbage collection, such as IL2CPP.
 - The full metadata information is not strictly required for 'private' methods or types so it is possible to strip it from the CLI image.
 - The metadata can be stored in more efficient form, such as the .NET Native metadata format.
-- The platform native executable format (ELF, Mach-O) can be used as envelope instead of PE to take advantage of platform OS loader.
+- As of .NET 10, the PE format is used on all platforms. A [future improvement](#platform-native-envelope-support) could be support for the platform native executable format (ELF, Mach-O) to take advantage of platform OS loader.
 
 
 ## Definition of Version Compatibility for Native Code
@@ -332,4 +332,8 @@ Another important observation is that `MethodTable` contains other very frequent
 
 # Current State
 
-The design and implementation is a work in progress under code name ReadyToRun (`FEATURE_READYTORUN`). RyuJIT is used as the code generator to produce the ReadyToRun images currently.
+As of .NET 6, the .NET SDK can publish applications as ReadyToRun using the `crossgen2` tool. The tool lives under `src/coreclr/aot/crossgen2`. Support in the coreclr runtime is under `FEATURE_READYTORUN`. RyuJIT is used as the code generator to produce the ReadyToRun images currently.
+
+## Platform-Native Envelope Support
+
+Through .NET 10, ReadyToRun uses the PE format on all platforms. In .NET 11, we plan to start adding support for other formats, with Mach-O being the first target. For more details, see [ReadyToRun Platform-Native Envelope](./readytorun-platform-native-envelope.md).

docs/design/coreclr/botr/readytorun-platform-native-envelope.md

@@ -0,0 +1,65 @@
+# ReadyToRun Platform Native Envelope
+
+Up through .NET 10, ReadyToRun (R2R) uses the Windows PE format as the native envelope on every platform. Non‑Windows platforms therefore load a PE file with the .NET loader performing the required fixups and code activation.
+
+In .NET 11, we plan to start adding support beyond the PE format. We will target support for:
+- Composite R2R only
+- Mach-O object files emitted by `crossgen2`
+- Runtime using a composite R2R image that is a Mach-O shared library
+   - Linking the object files into a shared library is expected to be handled by the SDK and is not covered in this document.
+
+The tentative high-level design is outlined below. As we implement this support, this document should be updated with more details and the [ReadyToRun overview](./readytorun-overview.md) and [ReadyToRun format](./readytorun-format.md) should be updated to reflect the changes.
+
+## crossgen2: producing Mach-O object files
+
+Mach‑O support will only be supported for composite ReadyToRun when the target OS is macOS. It will be opt-in via a new `crossgen2` flag:
+- `--obj-format macho`
+
+`crossgen2` will:
+- Produce a Mach-O object file as the composite R2R image with the `RTR_HEADER` export for the `READYTORUN_HEADER`.
+- Mark each input IL assembly as a component R2R assembly: `READYTORUN_FLAG_COMPONENT`.
+- Mark each input IL assembly with a new flag indicating that the associated composite image is in the platform-native format: `READYTORUN_FLAG_PLATFORM_NATIVE_IMAGE`
+
+`crossgen2` does not produce the final shared library. A separate SDK / build linking step must preserve the `RTR_HEADER` export in the final `dylib`.
+
+## Runtime: consuming a platform-native R2R image
+
+The runtime will be updated to handle platform-native R2R images during assembly load.
+
+1. Load IL assembly and determine if it is a R2R assembly.
+2. If it is not a component R2R assembly, proceed with existing R2R load logic.
+  - We will not have platform-native support for this scenario
+3. If it is a component R2R assembly with the new `READYTORUN_FLAG_PLATFORM_NATIVE_IMAGE` flag set:
+   a. Read `OwnerCompositeExecutable` value.
+   b. Invoke host callback with component assembly path and owner composite name.
+   c. On success, obtain pointer to composite `READYTORUN_HEADER` and use it for native method lookup / fixups.
+   d. On failure, fall back to IL/JIT path.
+4. If the platform-native flag is not set, proceed with existing R2R load logic (PE assembly lookup and load).
+
+### Host callback
+
+The [`host_runtime_contract`](/src/native/corehost/host_runtime_contract.h) will be updated with a new callback for getting native code information.
+
+```c
+struct native_code_context
+{
+    size_t size;                       // size of this struct
+    const char* assembly_path;         // component assembly path
+    const char* owner_composite_name;  // name from component R2R header
+};
+
+struct native_code_data
+{
+   size_t size;           // size of this struct
+   void* r2r_header_ptr;  // ReadyToRun header
+   size_t image_size;     // size of the image
+   void* image_base;      // base address where the image was loaded
+};
+
+bool get_native_code_data(
+   const struct native_code_context* context,
+   /*out*/ struct native_code_data* data
+);
+```
+
+This leaves it to the host to do the actual load (for example, `dlopen` of a shared library, using something statically linked into the host itself) of the platform-native image. It is also responsible for any caching desired.