Merge branch 'main' into feature/use-dllimport-generator

.config/dotnet-tools.json

@@ -15,7 +15,7 @@
       ]
     },
     "microsoft.dotnet.xharness.cli": {
-      "version": "1.0.0-prerelease.21501.2",
+      "version": "1.0.0-prerelease.21511.3",
       "commands": [
         "xharness"
       ]

.github/ISSUE_TEMPLATE/01_bug_report.yml

@@ -5,7 +5,7 @@ body:
   - type: markdown
     attributes:
       value: |
-        We welcome bug reports! Please see our [contribution guidelines](https://github.com/dotnet/runtime/blob/main/CONTRIBUTING.md) for more information on writing a good bug report. This template will help us gather the information we need to start the triage process.
+        We welcome bug reports! Please see our [contribution guidelines](https://github.com/dotnet/runtime/blob/main/CONTRIBUTING.md#writing-a-good-bug-report) for more information on writing a good bug report. This template will help us gather the information we need to start the triage process.
   - type: textarea
     id: background
     attributes:

.github/ISSUE_TEMPLATE/02_api_proposal.yml

@@ -55,6 +55,15 @@ body:
         ```     
     validations:
       required: true
+  - type: textarea
+    id: alternative-designs
+    attributes:
+      label: Alternative Designs
+      description: |
+        Please provide alternative designs. This might not be APIs; for example instead of providing new APIs an option might be to change the behavior of an existing API.
+      placeholder: Alternative designs
+    validations:
+      required: false
   - type: textarea
     id: risks
     attributes:

CONTRIBUTING.md

@@ -1,17 +1,71 @@
-Contribution to .NET Runtime
-=====================
+# Contribution to .NET Runtime
 
 You can contribute to .NET Runtime with issues and PRs. Simply filing issues for problems you encounter is a great way to contribute. Contributing implementations is greatly appreciated.
 
-## Contribution "Bar"
+## Reporting Issues
+
+We always welcome bug reports, API proposals and overall feedback. Here are a few tips on how you can make reporting your issue as effective as possible.
+
+### Identify Where to Report
+
+The .NET codebase is distributed across multiple repositories in the [dotnet organization](https://github.com/dotnet). Depending on the feedback you might want to file the issue on a different repo. Here are a few common repos:
+
+* [dotnet/runtime](https://github.com/dotnet/runtime) .NET runtime, libraries and shared host installers.
+* [dotnet/roslyn](https://github.com/dotnet/roslyn) C# and VB compiler.
+* [dotnet/aspnetcore](https://github.com/dotnet/aspnetcore) ASP.NET Core.
+* [dotnet/core](https://github.com/dotnet/core) Can be used to submit feedback if not sure what repo to use.
+
+### Finding Existing Issues
+
+Before filing a new issue, please search our [open issues](https://github.com/dotnet/runtime/issues) to check if it already exists.
+
+If you do find an existing issue, please include your own feedback in the discussion. Do consider upvoting (👍 reaction) the original post, as this helps us prioritize popular issues in our backlog.
+
+### Writing a Good API Proposal
+
+Please review our [API review process](https://github.com/dotnet/runtime/blob/main/docs/project/api-review-process.md) documents for guidelines on how to submit an API review. When ready to submit a proposal, please use the [API Suggestion issue template](https://github.com/dotnet/runtime/issues/new?assignees=&labels=api-suggestion&template=02_api_proposal.yml&title=%5BAPI+Proposal%5D%3A+).
+
+### Writing a Good Bug Report
+
+Good bug reports make it easier for maintainers to verify and root cause the underlying problem. The better a bug report, the faster the problem will be resolved. Ideally, a bug report should contain the following information:
+
+* A high-level description of the problem.
+* A _minimal reproduction_, i.e. the smallest size of code/configuration required to reproduce the wrong behavior.
+* A description of the _expected behavior_, contrasted with the _actual behavior_ observed.
+* Information on the environment: OS/distro, CPU arch, SDK version, etc.
+* Additional information, e.g. is it a regression from previous versions? are there any known workarounds?
+
+When ready to submit a bug report, please use the [Bug Report issue template](https://github.com/dotnet/runtime/issues/new?assignees=&labels=&template=01_bug_report.yml).
+
+#### Why are Minimal Reproductions Important?
+
+A reproduction lets maintainers verify the presence of a bug, and diagnose the issue using a debugger. A _minimal_ reproduction is the smallest possible console application demonstrating that bug. Minimal reproductions are generally preferable since they:
+
+1. Focus debugging efforts on a simple code snippet,
+2. Ensure that the problem is not caused by unrelated dependencies/configuration,
+3. Avoid the need to share production codebases.
+
+#### Are Minimal Reproductions Required?
+
+In certain cases, creating a minimal reproduction might not be practical (e.g. due to nondeterministic factors, external dependencies). In such cases you would be asked to provide as much information as possible, for example by sharing a memory dump of the failing application. If maintainers are unable to root cause the problem, they might still close the issue as not actionable. While not required, minimal reproductions are strongly encouraged and will significantly improve the chances of your issue being prioritized and fixed by the maintainers.
+
+#### How to Create a Minimal Reproduction
+
+The best way to create a minimal reproduction is gradually removing code and dependencies from a reproducing app, until the problem no longer occurs. A good minimal reproduction:
+
+* Excludes all unnecessary types, methods, code blocks, source files, nuget dependencies and project configurations.
+* Contains documentation or code comments illustrating expected vs actual behavior.
+* If possible, avoids performing any unneeded IO or system calls. For example, can the ASP.NET based reproduction be converted to a plain old console app?
+
+## Contributing Changes
 
 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.
 
 Contributions must also satisfy the other published guidelines defined in this document.
 
-## DOs and DON'Ts
+### DOs and DON'Ts
 
 Please do:
 
@@ -33,11 +87,11 @@ Please do not:
 * **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).
 
-## Breaking Changes
+### Breaking Changes
 
 Contributions must maintain [API signature](docs/coding-guidelines/breaking-changes.md#bucket-1-public-contract) and behavioral compatibility. Contributions that include [breaking changes](docs/coding-guidelines/breaking-changes.md) will be rejected. Please file an issue to discuss your idea or change if you believe that it may affect managed code compatibility.
 
-## Suggested Workflow
+### Suggested Workflow
 
 We use and recommend the following workflow:
 
@@ -67,11 +121,11 @@ We use and recommend the following workflow:
     - The next official build will automatically include your change.
     - You can delete the branch you used for making the change.
 
-## Up for Grabs
+### Up for Grabs
 
 The team marks the most straightforward issues as [up for grabs](https://github.com/dotnet/runtime/labels/up-for-grabs). This set of issues is the place to start if you are interested in contributing but new to the codebase.
 
-## Commit Messages
+### Commit Messages
 
 Please format commit messages as follows (based on [A Note About Git Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)):
 
@@ -90,15 +144,15 @@ Fix #42
 
 Also do your best to factor commits appropriately, not too large with unrelated things in the same commit, and not too small with the same small change applied N times in N different commits.
 
-## Contributor License Agreement
+### Contributor License Agreement
 
 You must sign a [.NET Foundation Contribution License Agreement (CLA)](https://cla.dotnetfoundation.org) before your PR will be merged. This is a one-time requirement for projects in the .NET Foundation. You can read more about [Contribution License Agreements (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) on Wikipedia.
 
 The agreement: [net-foundation-contribution-license-agreement.pdf](https://github.com/dotnet/home/blob/master/guidance/net-foundation-contribution-license-agreement.pdf)
 
 You don't have to do this up-front. You can simply clone, fork, and submit your pull-request as usual. When your pull-request is created, it is classified by a CLA bot. If the change is trivial (for example, you just fixed a typo), then the PR is labelled with `cla-not-required`. Otherwise it's classified as `cla-required`. Once you signed a CLA, the current and all future pull-requests will be labelled as `cla-signed`.
 
-## File Headers
+### File Headers
 
 The following file header is the used for .NET Core. Please use it for new files.
 
@@ -110,21 +164,21 @@ The following file header is the used for .NET Core. Please use it for new files
 - See [class.cpp](./src/coreclr/vm/class.cpp) for an example of the header in a C++ file.
 - See [List.cs](./src/libraries/System.Private.CoreLib/src/System/Collections/Generic/List.cs) for an example of the header in a C# file.
 
-## PR - CI Process
+### PR - CI Process
 
 The [dotnet continuous integration](https://dev.azure.com/dnceng/public/) (CI) system will automatically perform the required builds and run tests (including the ones you are expected to run) for PRs. Builds and test runs must be clean.
 
 If the CI build fails for any reason, the PR issue will be updated with a link that can be used to determine the cause of the failure.
 
-## PR Feedback
+### PR Feedback
 
 Microsoft team and community members will provide feedback on your change. Community feedback is highly valued. You will often see the absence of team feedback if the community has already provided good review feedback.
 
 One or more Microsoft team members will review every PR prior to merge. They will often reply with "LGTM, modulo comments". That means that the PR will be merged once the feedback is resolved. "LGTM" == "looks good to me".
 
 There are lots of thoughts and [approaches](https://github.com/antlr/antlr4-cpp/blob/master/CONTRIBUTING.md#emoji) for how to efficiently discuss changes. It is best to be clear and explicit with your feedback. Please be patient with people who might not understand the finer details about your approach to feedback.
 
-## Contributing Ports
+### Contributing Ports
 
 We encourage ports of CoreCLR to other platforms. There are multiple ports ongoing at any one time. You may be interested in one of the following ports:
 
@@ -145,7 +199,7 @@ Note: Add links to install instructions for each of these ports.
 
 Ports have a weaker contribution bar, at least initially. A functionally correct implementation is considered an important first goal. Performance, reliability and compatibility are all important concerns after that.
 
-### Copying Files from Other Projects
+#### 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.
 
@@ -157,7 +211,7 @@ The following rules must be followed for PRs that include files from another pro
 
 See [IdnMapping.cs](./src/libraries/System.Private.CoreLib/src/System/Globalization/IdnMapping.cs) for an example of a file copied from another project and attributed in the [CoreCLR 3rd party notices](./THIRD-PARTY-NOTICES.TXT) file.
 
-### Porting Files from Other Projects
+#### 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.
 

Directory.Build.props

@@ -62,6 +62,8 @@
 
     <NetFrameworkMinimum>net462</NetFrameworkMinimum>
     <NetFrameworkToolCurrent>net472</NetFrameworkToolCurrent>
+    <!-- Don't build for NETFramework during source-build. -->
+    <NetFrameworkToolCurrent Condition="'$(DotNetBuildFromSource)' == 'true'" />
   </PropertyGroup>
 
   <PropertyGroup>

README.md

@@ -24,7 +24,7 @@ Official Starting Page: https://dotnet.microsoft.com/
 
 We welcome contributions! Many people all over the world have helped make this project better.
 
-* [Contributing](CONTRIBUTING.md) explains what kinds of changes we welcome
+* [Contributing](CONTRIBUTING.md) explains what kinds of contributions we welcome
 - [Workflow Instructions](docs/workflow/README.md) explains how to build and test
 * [Get Up and Running on .NET Core](docs/project/dogfooding.md) explains how to get nightly builds of the runtime and its libraries to test them in your own projects.
 

docs/workflow/testing/mono/testing.md

@@ -20,6 +20,10 @@ cd src/tests
 ./build.sh excludemonofailures <release|debug>
 ```
 
+To build an individual test, test directory, or a whole subdirectory tree, use the `-test:`, `-dir:` or `-tree:` options (without the src/tests prefix)
+For example: `./build.sh excludemonofailures release -test:JIT/opt/InstructionCombining/DivToMul.csproj`
+
+
 Run individual test:
 ```
 cd src/mono
@@ -32,6 +36,24 @@ cd src/mono
 make run-tests-coreclr-all
 ```
 
+To debug a single test with `lldb`:
+
+1. Run the test at least once normally (or manually run the `mono.proj` `PatchCoreClrCoreRoot` target)
+2. Edit the `.sh` file for the test and change the line
+```
+    LAUNCHER="$_DebuggerFullPath "$CORE_ROOT/corerun" -p "System.Reflection.Metadata.MetadataUpdater.IsSupported=false"  ${__DotEnvArg}"
+```
+to add `--` after the debugger full path
+```
+    LAUNCHER="$_DebuggerFullPath -- "$CORE_ROOT/corerun" -p "System.Reflection.Metadata.MetadataUpdater.IsSupported=false"  ${__DotEnvArg}"
+```
+3. Run the shell script for the test case manually:
+```
+bash ./artifacts/tests/coreclr/OSX.x64.Release/JIT/opt/InstructionCombining/DivToMul/DivToMul.sh -coreroot=`pwd`/artifacts/tests/coreclr/OSX.x64.Release/Tests/Core_Root -debug=/usr/bin/lldb
+```
+4. In LLDB add the debug symbols for mono: `add-dsym <CORE_ROOT>/libcoreclr.dylib.dwarf`
+5. Run/debug the test
+
 ### WebAssembly:
 Build the runtime tests for WebAssembly
 ```

eng/Subsets.props

@@ -72,7 +72,7 @@
     <DefaultHostSubsets Condition="'$(RuntimeFlavor)' != '$(PrimaryRuntimeFlavor)' and '$(TargetsMobile)' != 'true'">host.native</DefaultHostSubsets>
 
     <DefaultPacksSubsets>packs.product</DefaultPacksSubsets>
-    <DefaultPacksSubsets Condition="'$(BuildMonoAOTCrossCompilerOnly)' != 'true'">$(DefaultPacksSubsets)+packs.tests</DefaultPacksSubsets>
+    <DefaultPacksSubsets Condition="'$(BuildMonoAOTCrossCompilerOnly)' != 'true' and '$(DotNetBuildFromSource)' != 'true'">$(DefaultPacksSubsets)+packs.tests</DefaultPacksSubsets>
     <DefaultPacksSubsets Condition="'$(DotNetBuildFromSource)' == 'true'">$(DefaultPacksSubsets)+packs.installers</DefaultPacksSubsets>
   </PropertyGroup>