Improvements to CoreCLR Building, Debugging, and Testing Documentation (dotnet#75569)

* Quality Week 2022: The First Step to a Better Documentation.

* Removed the Markdown Extension's additional development tags.

* Removed redundant stuff.

* Removed redundant stuff.

* Removed guide testing versions to avoid confusion that they would be the only supported versions.

* Addressed some Powershell comments, added a pointer to a yaml with links to other .NET sibling repos, and did a couple mini-corrections. Still got a few comments to address...

* Fixed a ';:' with Powershell's syntax.

* Addressed review comments: Redaction improvements, localization url's, improved code snippets, added info on individual subsets building configurations, changed COMPlus for DOTNET, and other misc improvements.

* Addressed remaining comments.

* Addressed some last comments regarding corerun, and the subset flags in the build scripts.

Co-authored-by: Ivan Diaz <[email protected]>

Author: ivdiazsa

README.md

@@ -1,15 +1,24 @@
 # .NET Runtime
+
 [![Build Status](https://dnceng.visualstudio.com/public/_apis/build/status/dotnet/runtime/runtime?branchName=main)](https://dnceng.visualstudio.com/public/_build/latest?definitionId=686&branchName=main)
 [![Help Wanted](https://img.shields.io/github/issues/dotnet/runtime/help%20wanted?style=flat-square&color=%232EA043&label=help%20wanted)](https://github.com/dotnet/runtime/labels/help%20wanted)
 [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/dotnet/runtime)
 [![Discord](https://img.shields.io/discord/732297728826277939?style=flat-square&label=Discord&logo=discord&logoColor=white&color=7289DA)](https://aka.ms/dotnet-discord)
 
+* [What is .NET?](#what-is-net)
+* [How can I contribute?](#how-can-i-contribute)
+* [Reporting security issues and security bugs](#reporting-security-issues-and-security-bugs)
+* [Filing issues](#filing-issues)
+* [Useful Links](#useful-links)
+* [.NET Foundation](#net-foundation)
+* [License](#license)
+
 This repo contains the code to build the .NET runtime, libraries and shared host (`dotnet`) installers for
 all supported platforms, as well as the sources to .NET runtime and libraries.
 
 ## What is .NET?
 
-Official Starting Page: https://dotnet.microsoft.com
+Official Starting Page: <https://dotnet.microsoft.com>
 
 * [How to use .NET](https://docs.microsoft.com/dotnet/core/get-started) (with VS, VS Code, command-line CLI)
   * [Install official releases](https://dotnet.microsoft.com/download)
@@ -25,23 +34,20 @@ 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 contributions we welcome
-- [Workflow Instructions](docs/workflow/README.md) explains how to build and test
+* [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.
 
 ## Reporting security issues and security bugs
 
-Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) <[email protected]>. 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).
+Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) <[email protected]>. 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).
 
 Also see info about related [Microsoft .NET Core and ASP.NET Core Bug Bounty Program](https://www.microsoft.com/msrc/bounty-dot-net-core).
 
 ## Filing issues
 
 This repo should contain issues that are tied to the runtime, the class libraries and frameworks, the installation of the `dotnet` binary (sometimes known as the `muxer`) and installation of the .NET runtime and libraries.
 
-For other issues, please use the following repos:
-
-- For overall .NET SDK issues, file in the [dotnet/sdk](https://github.com/dotnet/sdk) repo
-- For ASP.NET issues, file in the [dotnet/aspnetcore](https://github.com/dotnet/aspnetcore) repo.
+For other issues, please file them to their appropriate sibling repos. Their respective links are described in the [config issue template doc](/.github/ISSUE_TEMPLATE/config.yml).
 
 ## Useful Links
 
@@ -57,8 +63,8 @@ For other issues, please use the following repos:
 
 There are many .NET related projects on GitHub.
 
-- [.NET home repo](https://github.com/Microsoft/dotnet) - links to 100s of .NET projects, from Microsoft and the community.
-- [ASP.NET Core home](https://docs.microsoft.com/aspnet/core) - the best place to start learning about ASP.NET Core.
+* [.NET home repo](https://github.com/Microsoft/dotnet) - links to 100s of .NET projects, from Microsoft and the community.
+* [ASP.NET Core home](https://docs.microsoft.com/aspnet/core) - the best place to start learning about ASP.NET Core.
 
 This project has adopted the code of conduct defined by the [Contributor Covenant](https://contributor-covenant.org) to clarify expected behavior in our community. For more information, see the [.NET Foundation Code of Conduct](https://www.dotnetfoundation.org/code-of-conduct).
 

docs/workflow/Codespaces.md

@@ -1,11 +1,16 @@
 # Using Codespaces
-Codespaces allows you to develop in a Docker container running in the cloud. You can use an in-browser version of VS Code or the full VS Code application with the [GitHub Codespaces VS Code Extension](https://marketplace.visualstudio.com/items?itemName=GitHub.codespaces). This means you don't need to install dotnet/runtime's prerequisites on your current machine in order to develop in dotnet/runtime.
+
+* [Create a Codespace](#create-a-codespace)
+* [Updating dotnet/runtime's Codespaces Configuration](#updating-dotnetruntimes-codespaces-configuration)
+* [Testing out your Changes](#testing-out-your-changes)
+
+Codespaces allows you to develop in a Docker container running in the cloud. You can use an in-browser version of VS Code or the full VS Code application with the [GitHub Codespaces VS Code Extension](https://marketplace.visualstudio.com/items?itemName=GitHub.codespaces). This means you don't need to install any prerequisites on your current machine in order to develop in _dotnet/runtime_.
 
 ## Create a Codespace
 
-dotnet/runtime runs a nightly GitHub Action to build the latest code in the repo. This allows you to immediately start developing and testing after creating a codespace without having to build the whole repo. When the machine is created, it will have built the repo using the code as of 6 AM UTC that morning.
+The _dotnet/runtime_ repo runs a nightly GitHub Action to build the latest code in it. This allows you to immediately start developing and testing after creating a Codespace without having to build the whole repo. When the machine is created, it will have built the repo using the code as of 6 AM UTC of that morning.
 
-1. From https://github.com/dotnet/runtime, drop-down the `Code` button and select the `Codespaces` tab.
+1. From this [repository's root](https://github.com/dotnet/runtime), drop-down the _Code_ button and select the _Codespaces_ tab.
 
 ![New codespace button](https://docs.github.com/assets/cb-138303/images/help/codespaces/new-codespace-button.png)
 
@@ -17,29 +22,30 @@ dotnet/runtime runs a nightly GitHub Action to build the latest code in the repo
 
 ![Dev container configuration](./codespace-dev-container-configuration.png)
 
-    - For `libraries` work, pick `.devcontainer/libraries/devcontainer.json`.
-    - For `WASM` work, pick `.devcontainer/wasm/devcontainer.json`.
+* For `libraries` work, pick `.devcontainer/libraries/devcontainer.json`.
+* For `WASM` work, pick `.devcontainer/wasm/devcontainer.json`.
 
 4. Select the Machine type. For `dotnet/runtime`, it is recommended to select at least a `4-core` machine. You can also verify that a `Prebuild` is ready.
 
-![Codespace machine size](./codespace-machine-size.png)
+![Codespace machine size](codespace-machine-size.png)
 
-
-*If these instructions are out of date, see https://docs.github.com/codespaces/developing-in-codespaces/creating-a-codespace#creating-a-codespace for instructions on how to create a new codespace.*
+_If these instructions are out of date, see <https://docs.github.com/codespaces/developing-in-codespaces/creating-a-codespace#creating-a-codespace> for instructions on how to create a new Codespace._
 
 ## Updating dotnet/runtime's Codespaces Configuration
 
 The Codespaces configuration is spread across the following places:
 
-1. The [.devcontainer](../../.devcontainer) folder contains folders for each "development scenario":
-    - `libraries` - Used by developers working in `src/libraries`
-    - `wasm` - Used by developers working on the browser-wasm workload
-    - The `scripts` folder contains any scripts that are executed during the creation of the codespace. This has the build command that builds the entire repo for prebuilds.
-2. Each development scenario folder contains:
-    - `devcontainer.json` file configures the codespace and has VS Code / Environment settings
-    - The Dockerfile used to create the Docker image
-3. The GitHub Action can be configured by following the instructions at https://docs.github.com/codespaces/prebuilding-your-codespaces/configuring-prebuilds.
+1. The [.devcontainer](/.devcontainer) folder contains subfolders for each development scenario:
+    * _Libraries_: Used by developers working in `src/libraries`.
+    * _Wasm_: Used by developers working on the _browser-wasm_ workload.
+    * _Scripts_: Contains any scripts that are executed during the creation of the codespace. This has the build command that builds the entire repo for prebuilds.
+2. Each development scenario folder contains the following files:
+    * The `devcontainer.json` file that configures the codespace and has VS Code / Environment settings.
+    * The _Dockerfile_ used to create the Docker image
+3. The GitHub Action can be configured by following the instructions at <https://docs.github.com/codespaces/prebuilding-your-codespaces/configuring-prebuilds>.
+
+To test out changes to the `.devcontainer` files, you can follow the process in the [Applying Changes to your Configuration](https://docs.github.com/codespaces/customizing-your-codespace/configuring-codespaces-for-your-project#applying-changes-to-your-configuration) docs. This allows you to rebuild the Codespace privately before creating a PR.
 
-To test out changes to the `.devcontainer` files, you can follow the process in [Applying changes to your configuration](https://docs.github.com/codespaces/customizing-your-codespace/configuring-codespaces-for-your-project#applying-changes-to-your-configuration) docs. This allows you to rebuild the Codespace privately before creating a PR.
+## Testing out your Changes
 
-To test out your changes you can run the [Codespaces Prebuilds Action](https://github.com/dotnet/runtime/actions/workflows/codespaces/create_codespaces_prebuilds) in your fork against a branch with your changes.
+To test out your changes you can run the [Codespaces Prebuilds Action](https://github.com/dotnet/runtime/actions/workflows/codespaces/create_codespaces_prebuilds) in your fork against a branch with your changes.