Update workflow readme (#1512)

* Update workflow readme

* CR feedback and more detail

* Add daily workflow for libraries dev

* rebuild->build

* More updates

* typo:

* more

* More edits

* testing

* space:

docs/README.md

@@ -17,6 +17,8 @@ Getting Started
 Workflow (Building, testing, etc.)
 ===============
 
+If you want to contribute a code change to this repo, start here.
+
 - [Workflow Instructions](workflow/README.md)
 
 Design Docs

docs/workflow/README.md

@@ -2,6 +2,8 @@
 
 The repo can be built for the following platforms, using the provided setup and the following instructions. Before attempting to clone or build, please check these requirements.
 
+## Build Requirements
+
 | Chip  | Windows  | Linux    | macOS    | FreeBSD  |
 | :---- | :------: | :------: | :------: | :------: |
 | x64   | ✔ | ✔ | ✔ | ✔ |
@@ -10,22 +12,48 @@ The repo can be built for the following platforms, using the provided setup and
 | ARM64 | ✔ | ✔ |          |          |
 |       | [Requirements](requirements/windows-requirements.md) | [Requirements](requirements/linux-requirements.md) | [Requirements](requirements/macos-requirements.md) |
 
+Before proceeding further, please click on the link above that matches your machine and ensure you have installed all the pre-requisites for build to work.
+
 ## Concepts
 
-The runtime repo can be built from a regular, non-admin command prompt. The repository currently consists of three different partitions: the runtime (coreclr), libraries and the installer. For every partition there's a helper script available in the root (e.g. libraries.cmd/sh). The root build script (build.cmd/sh) should be used to build the entire repository.
+The runtime repo can be built from a regular, non-admin command prompt. The repository currently consists of three different major parts: the runtime (a.k.a. coreclr), the libraries and the installer. To build everything you use the root build script (build.cmd/sh), and you add the `-subsetCategory` flag to build just one part.
 
 For information about the different options available, supply the argument `-help|-h` when invoking the build script:
 ```
-libraries -h
+build -h
 ```
 On Unix, arguments can be passed in with a single `-` or double hyphen `--`.
 
-## Workflows
+## Configurations
+
+You may need to build the tree in a combination of configurations. This section explains why. 
+
+A quick reminder of some concepts -- see the [glossary](../project/glossary.md) for more on these:
+
+* **Debug configuration** -- Non-optimized code.  Asserts are enabled.
+* **Checked configuration** -- Optimized code. Asserts are enabled.  Only relevant to CoreCLR.
+* **Release configuration** -- Optimized code. Asserts are disabled. Runs at full speed, and suitable for performance profiling. Somewhat poorer debugging experience.
 
-For instructions on how to build, debug, test, etc. please visit the instructions in the workflow sub-folders.
+When we talk about mixing configurations, we're discussing three sub-components:
+
+* **CoreCLR** (often referred to as the runtime, most code under src/coreclr) -- this is the execution engine for managed code. It is written in C/C++. When built in a debug configuration, it is easier to debug into it, but it executes managed code more slowly - so slowly it will take a long time to run the managed code unit tests
+* **CoreLib** (also known as System.Private.CoreLib - code under src/coreclr/System.Private.CoreLib) -- this is the lowest level managed library. It has a special relationship with the runtime -- it must be in the matching configuration, e.g., if the runtime you are using was built in a debug configuration, this must be in a debug configuration
+* **All other libraries** (most code under src/libraries) -- the bulk of the libraries are oblivious to the configuration that CoreCLR/CoreLib were built in. Like most code they are most debuggable when built in a debug configuration, and, happily, they still run sufficiently fast in that configuration that it's acceptable for development work.
+
+### What does this mean for me?
+
+At this point you probably know what you are planning to work on first: the runtime or libraries.
+
+* if you're working in CoreCLR proper, you may want to build everything in the debug configuration, depending on how comfortable you are debugging optimized native code
+* if you're working in most libraries, you will want to use debug libraries with release CoreCLR and CoreLib, because the tests will run faster.
+* if you're working in CoreLib - you probably want to try to get the job done with release CoreCLR and CoreLib, and fall back to debug if you need to. The [Building libraries](building/libraries/README.md) document explains how you'll do this.
+
+Now you know about configurations and how we use them, you will want to read how to build what you plan to work on. Pick one of these:
 
 - [Building coreclr](building/coreclr/README.md)
 - [Building libraries](building/libraries/README.md)
 
+After that, here's information about how to run tests:
+
 - [Testing coreclr](testing/coreclr/testing.md)
 - [Testing libraries](testing/libraries/testing.md)

docs/workflow/building/coreclr/README.md

@@ -1,34 +1,32 @@
 # Building
 
-Once all the necessary tools are in place, building is trivial. Simply run coreclr.cmd/sh script that lives in the repository root.
+To build just CoreCLR, use the `--subsetCategory` flag to the `build.sh` (or `build.cmd`) at the repo root:
 
-```bat
-    .\coreclr.cmd
-
-    [Lots of build spew]
+```
+./build.sh --subsetCategory coreclr
+```
+or on Windows,
+```
+build.cmd --subsetCategory coreclr
+```
 
-    Product binaries are available at C:\git\runtime\artifacts\bin\coreclr\Windows_NT.x64.debug
-    Test binaries are available at C:\git\runtime\artifacts\tests\coreclr\Windows_NT.x64.debug
+By default, build generates a 'debug' build type, that includes asserts and is easier for some people to debug. If you want to make performance measurements, or just want tests to execute more quickly, you can also build the 'release' version which does not have these checks by adding the flag `-configuration release` (or `-c release`), for example
+```
+./build.sh --subsetCategory coreclr -configuration release
 ```
 
-As shown above, the product will be placed in
+This will produce outputs as follows:
 
 - Product binaries will be dropped in `artifacts\bin\coreclr\<OS>.<arch>.<flavor>` folder.
 - A NuGet package, Microsoft.Dotnet.CoreCLR, will be created under `artifacts\bin\coreclr\<OS>.<arch>.<flavor>\.nuget` folder.
 - Test binaries will be dropped under `artifacts\tests\coreclr\<OS>.<arch>.<flavor>` folder.
 
-By default, build generates a 'Debug' build type, that has extra checking (assert) compiled into it. You can
-also build the 'release' version which does not have these checks.
 
 The build places logs in `artifacts\log` and these are useful when the build fails.
 
 The build places all of its output in the `artifacts\obj\coreclr` directory, so if you remove that directory you can force a
 full rebuild.
 
-The build has a number of options that you can learn about using build -?.   Some of the more important options are
-
- * -skiptests - don't build the tests.   This can shorten build times quite a bit, but means you can't run tests.
- * -release - build the 'Release' build type that does not have extra development-time checking compiled in.
- You want this if you are going to do performance testing on your build.
+The build has a number of options that you can learn about using `build -?`. In particular  `-skiptests` skips building the tests, which makes the build quicker.
 
 See [Running Tests](../../testing/coreclr/testing.md) for instructions on running the tests.