Merge branch 'main' into spInterrupt

Author: VSadov

.github/ISSUE_TEMPLATE/05_blank_issue.md .github/ISSUE_TEMPLATE/04_blank_issue.md

@@ -18,3 +18,6 @@ contact_links:
   - name: Issue with WPF
     url:  https://github.com/dotnet/wpf/issues/new/choose
     about: Please open issues relating to WPF in dotnet/wpf.
+  - name: CI Known Issue Report
+    url: https://helix.dot.net/BuildAnalysis/CreateKnownIssues
+    about: Use the helper to create a Known Issue in CI if failures in your runs are unrelated to your change. See [Failure Analysis](https://github.com/dotnet/runtime/blob/main/docs/workflow/ci/failure-analysis.md#what-to-do-if-you-determine-the-failure-is-unrelated) for triage instructions.

.github/ISSUE_TEMPLATE/04_ci_known_issue.yml

@@ -127,3 +127,129 @@ The following are IL sequences involving the `box` instruction. They are used fo
 `box` ; `isinst` ; `unbox.any` – The box, `isint`, and unbox target types are all equal.
 
 `box` ; `isinst` ; `br_true/false` &ndash; The box target type is equal to the unboxed target type or the box target type is `Nullable<T>` and target type equalities can be computed.
+
+## Examples
+
+Below are valid and invalid examples of ByRefLike as Generic parameters. All examples use the **not official** syntax, `allows ref struct`, for indicating the Generic permits ByRefLike types.
+
+**1) Valid**
+```csharp
+class A<T1> where T1: allows ref struct
+{
+    public void M();
+}
+
+// The derived class is okay to lack the 'allows'
+// because the base permits non-ByRefLike (default)
+// _and_ ByRefLike types.
+class B<T2> : A<T2>
+{
+    public void N()
+        => M(); // Any T2 satisfies the constraints from A<>
+}
+```
+
+**2) Invalid**
+```csharp
+class A<T1>
+{
+    public void M();
+}
+
+// The derived class cannot push up the allows
+// constraint for ByRefLike types.
+class B<T2> : A<T2> where T2: allows ref struct
+{
+    public void N()
+        => M(); // A<> may not permit a T2
+}
+```
+
+**3) Valid**
+```csharp
+interface IA
+{
+    void M();
+}
+
+ref struct A : IA
+{
+    public void M() { }
+}
+
+class B
+{
+    // This call is permitted because no boxing is needed
+    // to dispatch to the method - it is implemented on A.
+    public static void C<T>(T t) where T: IA, allows ref struct
+        => t.M();
+}
+```
+
+**4) Invalid**
+```csharp
+interface IA
+{
+    public void M() { }
+}
+
+ref struct A : IA
+{
+    // Relies on IA::M() implementation.
+}
+
+class B
+{
+    // Reliance on a DIM forces the generic parameter
+    // to be boxed, which is invalid for ByRefLike types.
+    public static void C<T>(T t) where T: IA, allows ref struct
+        => t.M();
+}
+```
+
+**5) Valid**
+```csharp
+class A<T1> where T1: allows ref struct
+{
+}
+
+class B<T2>
+{
+    // The type parameter is okay to lack the 'allows'
+    // because the field permits non-ByRefLike (default)
+    // _and_ ByRefLike types.
+    A<T2> Field;
+}
+```
+
+**6) Invalid**
+```csharp
+class A<T1>
+{
+}
+
+class B<T2> where T2: allows ref struct
+{
+    // The type parameter can be passed to
+    // the field type, but will fail if
+    // T2 is a ByRefLike type.
+    A<T2> Field;
+}
+```
+
+**7) Invalid**
+```csharp
+class A
+{
+    virtual void M<T1>() where T1: allows ref struct;
+}
+
+class B : A
+{
+    // Override methods need to match be at least
+    // as restrictive with respect to constraints.
+    // If a user has an instance of A, they are
+    // not aware they could be calling B.
+    override void M<T2>();
+}
+```

.github/ISSUE_TEMPLATE/config.yml

@@ -12,6 +12,19 @@
 
 ## Triaging errors seen in CI
 
+## Summary
+
+**Passing Build Analysis is required to merge into the runtime repo**.
+
+To resolve failures, do the following, in order:
+
+1. Fix the problem if your PR is the cause.
+2. For all failures not in the "Known test errors" section, [try to file a Known Build Error issue](#what-to-do-if-you-determine-the-failure-is-unrelated).
+3. If all else fails, perform a [manual bypass](#bypassing-build-analysis).
+
+
+## Details
+
 In case of failure, any PR on the runtime will have a failed GitHub check - PR Build Analysis - which has a summary of all failures, including a list of matching  known issues as well as any regressions introduced to the build or the tests. This tab should be your first stop for analyzing the PR failures.
 
 ![Build analysis check](analysis-check.png)
@@ -78,6 +91,7 @@ If you have considered all the diagnostic artifacts and determined the failure i
     ````
     It already contains most of the essential information, but *it is very important that you fill out the json blob*.
 
+    - You can now use the [Build Analysis Known Issue Helper](https://helix.dot.net/BuildAnalysis/CreateKnownIssues) to create an issue. It assists in adding the right set of labels, fill the necessary paths in the json blob, and it will validate that it matches the text presented for the issue found in the logs.
     - You can add into the `ErrorMessage` field the string that you found uniquely identifies the issue. In case you need to use a regex, use the `ErrorPattern` field instead. This is a limited to a single-line, non-backtracking regex as described [here](https://github.com/dotnet/arcade/blob/main/Documentation/Projects/Build%20Analysis/KnownIssues.md#regex-matching). This regex also needs to be appropriately escaped. Check the [arcade known issues](https://github.com/dotnet/arcade/blob/main/Documentation/Projects/Build%20Analysis/KnownIssues.md#filling-out-known-issues-json-blob) documentation for a good guide on proper regex and JSON escaping.
     - The field `ExcludeConsoleLog` describes if the execution logs should be considered on top of the individual test results. **For most cases, this should be set to `true` as the failure will happen within a single test**. Setting it to `false` will mean all failures within an xUnit set of tests will also get attributed to this particular error, since there's one log describing all the problems. Due to limitations in Known Issues around rate limiting and xUnit resiliency, setting `ExcludeConsoleLog=false` is necessary in two scenarios:
       + Nested tests as reported to Azure DevOps. Essentially this means theory failures, which look like this when reported in Azure DevOps: ![xUnit theory seen in azure devops](theory-azdo.png).
@@ -95,6 +109,16 @@ After you do this, if the failure is occurring frequently as per the data captur
 
 There are plenty of intermittent failures that won't manifest again on a retry. Therefore these steps should be followed for every iteration of the PR build, e.g. before retrying/rebuilding.
 
+### Bypassing build analysis
+
+To unconditionally bypass the build analysis check (turn it green), you can add a comment to your PR with the following text:
+
+```
+/ba-g <reason>
+```
+
+For more information, see https://github.com/dotnet/arcade/blob/main/Documentation/Projects/Build%20Analysis/EscapeMechanismforBuildAnalysis.md
+
 ### Examples of Build Analysis
 
 #### Good usage examples