[docs] BuildFromSource.md fixes + edit pass (#45828)

* [docs] Edit pass on BuildFromSource.md

* Minor edits + typo fix

docs/BuildFromSource.md

@@ -1,162 +1,171 @@
-# Build the ASP.NET Core Repo
+# Build the ASP.NET Core repo
 
 If you're reading these instructions, you're probably a contributor looking to understand how to build this repo locally on your machine so that you can build, debug, and test changes.
 
-To get started, you'll need to have a fork of the repo cloned locally. This workflow assumes that you have [git installed on your development machine](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
+To get started, fork this repo and then clone it locally. This workflow assumes that you have [git installed on your development machine](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
 
-1. To create your own fork, click the **Fork** button from our GitHub repo as a signed-in user and your own fork will be created. For more information on managing forks, you can review the [GitHub docs on working with forks](https://docs.github.com/en/github/collaborating-with-pull-requests/working-with-forks).
+1. To create your own fork of the repo, sign in to GitHub and click the repo's **Fork** button. For more information on managing forks, you can review the [GitHub docs on working with forks](https://docs.github.com/en/github/collaborating-with-pull-requests/working-with-forks).
 
-2. Clone the repo locally using the `git clone` command. Since this repo contains submodules, you'll need to pass the `--recursive` flag to pull the sources for the submodules locally.
+1. Clone the repo locally using the `git clone` command. Since this repo contains submodules, include the `--recursive` argument to pull the sources for the submodules locally.
 
-```
-git clone --recursive https://github.com/YOUR_USERNAME/aspnetcore
-```
+    ```bash
+    git clone --recursive https://github.com/YOUR_USERNAME/aspnetcore
+    ```
 
-> :bulb: All other steps below will be against your fork of the aspnetcore repo (e.g. `YOUR_USERNAME/aspnetcore`), not the official `dotnet/aspnetcore` repo.
+    If you've already cloned the repo without passing the `--recursive` flag, fetch the submodule sources at any time with:
 
-> :bulb: If you've already cloned the repo without passing the `--recursive` flag, you can fetch submodule sources at any time using:
->
-> ```bash
-> git submodule update --init --recursive
-> ```
+    ```bash
+    git submodule update --init --recursive
+    ```
 
-The experience for building the repo is slightly different based on what environment you are looking to develop in. Select one of the links below to navigate to the instructions for your environment of choice.
+    > :bulb: All other steps below will be against your fork of the aspnetcore repo (e.g. `YOUR_USERNAME/aspnetcore`), not the official `dotnet/aspnetcore` repo.
 
-- [Visual Studio on Windows](#visual-studio-on-windows)
-- [VS Code (or other editors) on Windows, Linux, Mac](#visual-studio-code-on-windows-linux-mac)
-- [Codespaces on GitHub](#codespaces-on-github)
+1. If you're on Windows, update the PowerShell execution policy on your machine. For more information on execution policies, review [the execution policy docs](https://docs.microsoft.com/powershell/module/microsoft.powershell.security/set-executionpolicy). To do this, open a PowerShell prompt and issue the following command:
+
+    ```powershell
+    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+    ```
 
-3. If you are on Windows, update the Powershell execution policy on your machine. For more information on execution policies, review [the execution policy docs](https://docs.microsoft.com/powershell/module/microsoft.powershell.security/set-executionpolicy). To do this, open a Powershell prompt and issue the following command:
+    > :warning: All Windows commands below assume a PowerShell prompt.
 
-```powershell
-Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
-```
+The steps you follow next depend on your preferred development environment:
 
-> :warning: All Windows commands below assume a Powershell prompt.
+- [Visual Studio on Windows](#visual-studio-on-windows)
+- [Visual Studio Code (VS Code) or other editors on Windows, Linux, Mac](#visual-studio-code-or-other-editor-on-windows-linux-mac)
+- [Codespaces on GitHub](#codespaces-on-github)
 
 ## Visual Studio on Windows
 
-1. In order to install Visual Studio on your machine, you can use the official installer script in the repo.
+1. To install Visual Studio on your machine, use the official installer script in the repo.
 
-> :warning: Even if you have the appropriate Visual Studio installed on your machine, we recommend running this installation script to make sure that the correct Visual Studio components are installed.
-> To modify an existing Visual Studio installation, follow [the instructions for installing from a configuration file](https://learn.microsoft.com/en-us/visualstudio/install/import-export-installation-configurations?view=vs-2022#import-a-configuration) and use the `.vsconfig` file located in the root of the repository.
+    > :warning: Even if you have Visual Studio installed on your machine, we recommend running this installation script to make sure that the correct Visual Studio components are installed.
+    >
+    > To modify an existing Visual Studio installation, [follow the instructions for installing from a configuration file](https://learn.microsoft.com/visualstudio/install/import-export-installation-configurations?view=vs-2022#import-a-configuration) and use the `.vsconfig` file located in the root of the repository:
 
-```powershell
-./eng/scripts/InstallVisualStudio.ps1
-```
+    ```powershell
+    ./eng/scripts/InstallVisualStudio.ps1
+    ```
 
-2. Before opening the project in Visual Studio, run the `restore` script locally to install the required dependencies and setup the repo. The `restore` script is located in the root of the repo.
+1. Before you open project in Visual Studio, install the required dependencies and set up the repo by running the `restore.cmd` script in the root of the repo:
 
-```powershell
-.\restore.cmd
-```
+    ```powershell
+    ./restore.cmd
+    ```
 
-3. Typically, you'll want to focus on a single project within the repo. You can leverage the `startvs.cmd` command to launch Visual Studio within a particular project area. For example, to launch Visual Studio in the `Components` project.
+1. You'll typically focus on one project in the repo. You can use the `startvs.cmd` command to launch Visual Studio in a particular project area. For example, to launch Visual Studio in the `Components` project:
 
-```powershell
-cd src\Components
-.\startvs.cmd
-```
+    ```powershell
+    cd src\Components
+    ./startvs.cmd
+    ```
 
-<details>
- <summary>A brief interlude on Solution Files</summary>
+    <details>
+     <summary>A brief interlude on Solution Files</summary>
 
-We have a single .sln file for all of ASP.NET Core, but most people don't work with it directly because Visual Studio doesn't currently handle projects of this scale very well.
+    We have a single _.sln_ file for all of ASP.NET Core, but most people don't work with it directly because Visual Studio doesn't currently handle projects of this scale very well.
 
-Instead, we have many Solution Filter (.slnf) files which include a sub-set of projects. For more information on solution files, you can review the [official Visual Studio doc](https://docs.microsoft.com/visualstudio/ide/filtered-solutions).
+    Instead, we have many Solution Filter (.slnf) files which include a sub-set of projects. For more information on solution files, you can review the [official Visual Studio doc](https://docs.microsoft.com/visualstudio/ide/filtered-solutions).
 
-These principles guide how we create and manage .slnf files:
-* Solution files are not used by CI or command line build scripts. They are meant for use by developers only.
-* Solution files group together projects which are frequently edited at the same time.
-* Can't find a solution that has the projects you care about? Feel free to make a PR to add a new .slnf file.
+    These principles guide how we create and manage .slnf files:
 
-</details>
+    - Solution files are not used by CI or command line build scripts. They are meant for use by developers only.
+    - Solution files group together projects which are frequently edited at the same time.
+    - Can't find a solution that has the projects you care about? Feel free to make a PR to add a new .slnf file.
 
-5. You can now build, debug, and test using Visual Studio. For more information on using Visual Studio to build and run projects, you can review the [official Visual Studio docs](https://docs.microsoft.com/en-us/visualstudio/get-started/csharp/run-program).
+    </details>
+
+1. You can now build, debug, and test using Visual Studio. For more information on using Visual Studio to build and run projects, you can review the [official Visual Studio docs](https://docs.microsoft.com/visualstudio/get-started/csharp/run-program).
 
 ## Visual Studio Code or other editor on Windows, Linux, Mac
 
-> :bulb: The instructions below use Visual Studio code as the editor of choice but the same instructions can be used for any other text editor by replacing the `code` command with an invocation to your editor of choice.
+> :bulb: These steps also apply to editors other than Visual Studio Code. If you use a different editor, replace `code` in the steps below with your editor's equivalent command.
 
-1. In order to use Visual Studio Code for development on this repo, you'll need to have [VS Code](https://code.visualstudio.com/) installed and [the `code` command installed](https://code.visualstudio.com/docs/setup/mac#_launching-from-the-command-line) on your machine.
+1. To use Visual Studio Code for developing in this repo, you need [Visual Studio Code installed](https://code.visualstudio.com/) and the ability to [launch `code` from the command line](https://code.visualstudio.com/docs/setup/mac#_launching-from-the-command-line).
 
-2. The repo contains some JavaScript dependencies, so you will need to install [Node](https://nodejs.org/en/) and [yarn](https://yarnpkg.com/) on your machine.
+1. This repo has JavaScript dependencies, so you need [Node.js](https://nodejs.org/en/) and [yarn](https://yarnpkg.com/) installed on your machine.
 
-3. Prior to opening the code in Visual Studio code, you'll need to run the `restore` script locally to install the required dotnet dependencies and setup the repo. The `restore` script is located in the root of the repo.
+1. Before you open anything in Visual Studio Code, run the `restore` script in the root of the repo to install the required .NET dependencies.
 
-```bash
-# Linux or Mac
-./restore.sh
-```
+    ```bash
+    # Linux or Mac
+    ./restore.sh
+    ```
 
-```powershell
-# Windows
-./restore.cmd
-```
+    ```powershell
+    # Windows
+    ./restore.cmd
+    ```
 
-4. After the restore script has finished executing, activate the locally installed .NET by running the following command.
+1. After the `restore` script finishes, activate the locally installed .NET by running the following command.
 
-```bash
-# Linux or Mac
-source activate.sh
-```
+    ```bash
+    # Linux or Mac
+    source activate.sh
+    ```
 
-```powershell
-# Windows - note the leading period followed by a space
-. ./activate.ps1
-```
+    ```powershell
+    # Windows - note the leading period followed by a space
+    . ./activate.ps1
+    ```
 
-5. After activating the locally installed .NET, you can open your project of choice by running the `code` command in the directory of choice. For example, if you want to modify code in the `src/Http` project, you can use the following:
+1. After you've activated the locally installed .NET, open the project you want to modify by running the `code` command in the project's directory. For example, if you want to modify the`src/Http` project:
 
-```bash
-cd src/Http
-code .
-```
+    ```bash
+    cd src/Http
+    code .
+    ```
 
-If you are using a different editor, replace `code` with `vim` or whatever that editor is.
+    > :information_source: If you're using a different editor, replace `code` with your editor's equivalent launch command (for example, `vim`).
 
-6. Once you've opened the project in VS Code, you can build and test changes by running the `./build.sh` command in the terminal.
+1. Once you've opened the project in VS Code, you can build and test changes by running the `./build.sh` command in the terminal.
 
-> :bulb: The `build.sh` or `build.cmd` script will be local to the directory of the project that you have opened. For example, the script located in the `src/Http` directory.
+    > :bulb: The `build.sh` or `build.cmd` script will be local to the directory of the project you opened. For example, the script located in the `src/Http` directory.
 
-```bash
-# Linux or Mac
-./build.sh
-./build.sh -test
-```
+    ```bash
+    # Linux or Mac
+    ./build.sh
+    ./build.sh -test
+    ```
 
-```powershell
-# Windows
-./build.cmd
-./build.cmd -test
-```
+    ```powershell
+    # Windows
+    ./build.cmd
+    ./build.cmd -test
+    ```
 
-7. Alternatively, you can use the `dotnet test` and `dotnet build` commands directly once you've activated the locally installed .NET SDK.
+1. Alternatively, you can use the `dotnet test` and `dotnet build` commands directly once you've activated the locally installed .NET SDK.
 
-```bash
-# Linux or Mac
-source activate.sh
-dotnet build
-dotnet test --filter "MySpecificUnitTest"
-```
+    ```bash
+    # Linux or Mac
+    source activate.sh
+    dotnet build
+    dotnet test --filter "MySpecificUnitTest"
+    ```
 
-```powershell
-# Windows
-. ./activate.ps1
-dotnet build
-dotnet test --filter "MySpecificUnitTest"
-```
+    ```powershell
+    # Windows
+    . ./activate.ps1
+    dotnet build
+    dotnet test --filter "MySpecificUnitTest"
+    ```
 
 ## Codespaces on GitHub
 
-If you have [Codespaces enabled on your GitHub user account](https://github.com/codespaces), you can use Codespaces to make code changes in the repo using a cloud based editor environment.
+If you have [Codespaces enabled on your GitHub user account](https://github.com/codespaces), you can use Codespaces to make code changes in the repo by using a cloud-based editor environment.
+
+1. Navigate to your fork of the repo and select the branch in which you'd like to make your code changes.
+
+    If you haven't yet created a working branch, do so by using the GitHub UI or locally by first checking out and then pushing the new branch.
+
+1. Open a Codespace for your branch by selecting the **Code** button > **Codespaces** tab > **Create codespace**.
+
+    ![How to open a project in Codespaces](https://user-images.githubusercontent.com/1857993/136060792-6b4c6158-0a2c-4dd6-8639-08d83da6d2d1.png)
 
-1. Navigate to the fork and branch you would like to make code changes in. Note: if you have not created a new branch yet, do so using the GitHub UI or locally checking out and pushing a new branch.
-2. Open a Codespace for your branch by navigating to the "Code" button > selecting the "Codespaces" tab > clicking the "New codespace" button.
+    The Codespace will spend a few minutes building and initializing. Once it's done, you'll be able to navigate the Codespace in a web-based VS Code environment.
 
-![How to open a project in Codespaces](https://user-images.githubusercontent.com/1857993/136060792-6b4c6158-0a2c-4dd6-8639-08d83da6d2d1.png)
+1. You can use the `dotnet build` and `dotnet test` commands to build and test the repo.
 
-3. The Codespace will spend a few minutes building and initializating. Once this is done, you'll be able to navigate the Codespace in a web-based VS Code environment. You can use the `dotnet build` and `dotnet test` commands to build and test the repo. Note: you do not need to activate the locally installed .NET SDK or run the restore script. This is done as part of the initialization process.
+    You don't need to activate the locally installed .NET SDK or run the `restore` script because it's done during the Codespace initialization process.
 
 ---
 
@@ -164,13 +173,13 @@ If you have [Codespaces enabled on your GitHub user account](https://github.com/
 
 See [BuildErrors](https://github.com/dotnet/aspnetcore/blob/main/docs/BuildErrors.md) for a description of common issues you might run into while building the repo.
 
-## A Guide to the Build Script
+## Guide to the build script
 
 This ASP.NET Core repo contains a top-level build script located at `eng/build.cmd` and `eng/build.sh` and local build scripts within each directory. The scripts can be used to restore, build, and test the repo with support for a variety of flags. This section documents the common flags and some recommended invocation patterns.
 
-> :warning: It is _not_ recommended to run the top-level build script for the repo. You'll rarely need to build the entire repo and building a particular sub-project is usually sufficient for your workflow.
+> :warning: We do _not_ recommend running the top-level build script for the repo. You'll rarely need to build the entire repo; building a sub-project is usually sufficient for your workflow.
 
-### Common Arguments
+### Common arguments
 
 Common arguments that can be invoked on the `build.cmd` or `build.sh` scripts include:
 
@@ -180,14 +189,14 @@ Common arguments that can be invoked on the `build.cmd` or `build.sh` scripts in
 | TargetArchitecture | The CPU architecture to build for (x64, x86, arm, arm64).               |
 | TargetOsName       | The base runtime identifier to build for (win, linux, osx, linux-musl). |
 
-### Common Invocations
+### Common invocations
 
 | Command                              | What does it do?                                                                                          |
 | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
 | `.\build.cmd -Configuration Release` | Build projects in a subdirectory using a `Release` configuration. Can be run in any project subdirectory. |
 | `.\build.cmd -test`                  | Run all unit tests in the current project. Can be run in any project subdirectory.                        |
 
-### Repo-level Invocations
+### Repo-level invocations
 
 While it's typically better to use the project-specific build scripts, the repo-level build scripts located in the `eng` directory can also be used for project-specific invocations.
 
@@ -197,11 +206,11 @@ While it's typically better to use the project-specific build scripts, the repo-
 | `.\eng\build.cmd -test -projects .\src\Framework\test\Microsoft.AspNetCore.App.UnitTests.csproj` | Run all the unit tests in the `Microsoft.AspNetCore.App.UnitTests` project.                                                             |
 | `.\eng\build.cmd -noBuildNative -noBuildManage`                                                  | Builds the repo and skips native and managed projects, a quicker alternative to `./restore.cmd`. Must be run from the root of the repo. |
 
-## A Complete List of Repo Dependencies
+## Complete list of repo dependencies
 
-To support building and testing all the projects in the repo, various dependencies need to be installed. Some dependencies are required regardless of what project area you want to work in. Other dependencies are optional depending on the project. Most required dependencies are installed automatically by the `restore` scripts, included by default in most modern operating systems, or installed automatically by the Visual Studio installer.
+To support building and testing the projects in the repo, several dependencies must be installed. Some dependencies are required regardless of the project area you want to work in. Other dependencies are optional depending on the project. Most required dependencies are installed automatically by the `restore` scripts, included by default in most modern operating systems, or installed automatically by the Visual Studio installer.
 
-### Required Dependencies
+### Required dependencies
 
 | Dependency                                                              | Use                                                                                                                               |
 | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
@@ -210,7 +219,7 @@ To support building and testing all the projects in the repo, various dependenci
 | [curl](https://curl.haxx.se/)/[wget](https://www.gnu.org/software/wget) | Used for downloading installation files and assets from the web.                                                                  |
 | [tar](https://man7.org/linux/man-pages/man1/tar.1.html)                 | Used for unzipping installation assets. Included by default on macOS, Linux, and Windows 10 and above.                            |
 
-### Optional Dependencies
+### Optional dependencies
 
 | Dependency                                                   | Use                                                                                                                                                           | Notes                                                                                                                                               |
 | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -219,5 +228,5 @@ To support building and testing all the projects in the repo, various dependenci
 | [Chrome](https://www.google.com/chrome/)                     | Required when running tests with Selenium or Playwright in the projects above. When using Playwright, the dependency is automatically installed.              |                                                                                                                                                     |
 | [Java Development Kit (v11 or newer)](https://jdk.java.net/) | Required when building the Java SignalR client. Can be installed using the `./eng/scripts/InstallJdk.ps1` script on Windows.                                  | Ensure that the `JAVA_HOME` directory points to the installation and that the `PATH` has been updated to include the `$(jdkInstallDir)/bin` folder. |
 | [Wix](https://wixtoolset.org/releases/)                      | Required when working with the Windows installers in the [Windows installers project](https://github.com/dotnet/aspnetcore/tree/main/src/Installers/Windows). |                                                                                                                                                     |
-| [NodeJS](https://nodejs.org/en/)                             | Used for building JavaScript assets in the repo, such as those in Blazor and SignalR.                                                                         | Required a minimum version of the current NodeJS LTS.                                                                                               |
+| [Node.js](https://nodejs.org/en/)                             | Used for building JavaScript assets in the repo, such as those in Blazor and SignalR.                                                                         | Required a minimum version of the current NodeJS LTS.                                                                                               |
 | [Yarn](https://yarnpkg.com/)                                 | Used for installing JavaScript dependencies in the repo, such as those in Blazor and SignalR.                                                                 |                                                                                                                                                     |