Organize some markdowns and fix links (#1159)

* Move files into hierarchy

* fix more links

* Fix botr and features links

* Remove bad apostrophe

* spelling

* Apply suggestions from code review
Co-Authored-By: NYoussef Victor <31348972+Youssef1313@users.noreply.github.com>

* Update docs/coding-guidelines/package-projects.md
Co-Authored-By: NJan Kotas <jkotas@microsoft.com>
Co-authored-by: NYoussef Victor <31348972+Youssef1313@users.noreply.github.com>
Co-authored-by: NJan Kotas <jkotas@microsoft.com>

CONTRIBUTING.md

@@ -157,6 +157,6 @@ See [IdnMapping.cs](./src/libraries/System.Private.CoreLib/src/System/Globalizat
 
 ### 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.
+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.
 
 [Clean-room](https://en.wikipedia.org/wiki/Clean_room_design) implementations of existing algorithms that are not permissively licensed will generally not be accepted. If you want to create or nominate such an implementation, please create an issue to discuss the idea.

README.md

@@ -22,7 +22,8 @@ Official Starting Page: https://dotnet.microsoft.com/
 
 We welcome contributions! Many people all over the world have helped make this project better.
 
-For further information see [Contributing](CONTRIBUTING.md).
+* [Contributing](CONTRIBUTING.md) explains what kinds of changes we welcome
+- [Workflow Instructions](docs/workflow/README.md) explains how to build and test
 
 ## Reporting security issues and security bugs
 

docs/README.md

@@ -14,13 +14,6 @@ Getting Started
 - [Installing the .NET SDK](https://dotnet.microsoft.com/download)
 - [Official .NET Docs](https://docs.microsoft.com/dotnet/core/)
 
-Software requirements
-===============
-
-- [Windows Requirements](workflow/windows-requirements.md)
-- [Linux Requirements](workflow/linux-requirements.md)
-- [MacOS Requirements](workflow/macos-requirements.md)
-
 Workflow (Building, testing, etc.)
 ===============
 

docs/coding-guidelines/EventLogging.md

@@ -6,9 +6,9 @@ Event Logging is a mechanism by which CoreClr can provide a variety of informati
 
 # Adding Events to the Runtime
 
-- Edit the [Event manifest](../../src/vm/ClrEtwAll.man) to add a new event. For guidelines on adding new events, take a  look at the existing events in the manifest and this guide for [ETW Manifests](https://msdn.microsoft.com/en-us/library/dd996930%28v=vs.85%29.aspx?f=255&MSPPError=-2147217396).
+- Edit the [Event manifest](../../src/coreclr/src/vm/ClrEtwAll.man) to add a new event. For guidelines on adding new events, take a  look at the existing events in the manifest and this guide for [ETW Manifests](https://msdn.microsoft.com/en-us/library/dd996930%28v=vs.85%29.aspx?f=255&MSPPError=-2147217396).
 - The build system should automatically generate the required artifacts for the added events.
-- Add entries in the [exclusion list](../../src/vm/ClrEtwAllMeta) if necessary
+- Add entries in the [exclusion list](../../src/coreclr/src/vm/ClrEtwAllMeta.lst) if necessary
 - The Event Logging Mechanism provides the following two functions, which can be used within the VM:
 	- **FireEtw**EventName, this is used to trigger the event
 	- **EventEnabled**EventName, this is used to see if any consumer has subscribed to this event
@@ -16,4 +16,4 @@ Event Logging is a mechanism by which CoreClr can provide a variety of informati
 
 # Adding New Logging System
 
-Though the the Event logging system was designed for ETW, the build system provides a mechanism, basically an [adapter script- genXplatEventing.py](../../src/scripts/genXplatEventing.py) so that other Logging System can be added and used by CoreClr. An Example of such an extension for [LTTng logging system](https://lttng.org/) can be found in [genXplatLttng.py](../../src/scripts/genXplatLttng.py )
+Though the the Event logging system was designed for ETW, the build system provides a mechanism, basically an [adapter script- genEventing.py](../../src/coreclr/src/scripts/genEventing.py) so that other Logging System can be added and used by CoreClr. An Example of such an extension for [LTTng logging system](https://lttng.org/) can be found in [genLttngProvider.py](../../src/coreclr/src/scripts/genLttngProvider.py )

docs/coding-guidelines/adding-api-guidelines.md

@@ -4,17 +4,16 @@ Recommended reading to better understand this document:
 | [Package-Projects](package-projects.md)
 
 # Add APIs
-- [Determining versions and targets](#determining-versions-and-targets)
-- [Making the changes in repo](#making-the-changes-in-repo)
-- [FAQ](#faq)
 
-## Determining versions and targets
-
-1. [Determine what library](#determine-what-library) the API goes into.
-2. [Determine the target framework](#determine-target-framework) for the library that will contain the API.
-3. [Determine the version](#determine-library-version) for the library that will contain the API.
+- [Add APIs](#add-apis)
+    - [Determine what library](#determine-what-library)
+    - [Determine target framework](#determine-target-framework)
+    - [Determine library version](#determine-library-version)
+  - [Making the changes in repo](#making-the-changes-in-repo)
+  - [FAQ](#faq)
 
 ### Determine what library
+
 - Propose a library for exposing it as part of the [API review process](http://aka.ms/apireview).
 - Keep in mind the API might be exposed in a reference assembly that
 doesn't match the identity of the implementation. There are many reasons for this but
@@ -23,9 +22,10 @@ different platforms while sharing a common API surface and allowing us to refact
 the implementation without compat concerns in future releases.
 
 ### Determine target framework
+
 `netstandard` or `netcoreapp` is the target framework version currently under development.
 
-- If the library is [part of netstandard](#isnetstandard)
+- If the library is [part of netstandard](#faq)
   - Your target framework should be `netstandard`
   - If it is a new API only available on .NET Core then it will be added to `netcoreapp`
 - If the library is not part of netstandard
@@ -83,4 +83,4 @@ project references across the projects. You also need to be sure to leave type-f
 where you removed types in order to maintain back-compat.
 
 
-[net-standard table]: https://docs.microsoft.com/en-us/dotnet/standard/net-standard#net-implementation-support
\ No newline at end of file
+[net-standard table]: https://docs.microsoft.com/en-us/dotnet/standard/net-standard#net-implementation-support

docs/coding-guidelines/package-projects.md

@@ -214,9 +214,10 @@ Sample `System.IO.FileSystem.pkgproj`
 ```
 
 ## Asset selection
+
 The makeup of a package folder is primarily a grouping of project references to the projects that compose that package.  Settings within each referenced project determines where that asset will be placed in the package.  For example, reference assembly projects will be placed under the `ref/{targetMoniker}` folder in the package and implementations will be under either `lib/{targetMoniker}` or `runtimes/{rid}/lib/{targetMoniker}`.  Whenever NuGet evaluates a package in the context of a referencing project it will choose the best compile time asset (preferring `ref`, then falling back to `lib`) and runtime asset (preferring `runtimes/{rid}/lib` and falling back to `lib`) for every package that is referenced.  For more information see http://docs.nuget.org/.
 
-Asset projects (`.csproj`, `.vbproj`, or `.depproj`) can control their `{targetMoniker}` using the `PackageTargetFramework` property in the project file.  Similarly `{rid}` is controlled using the `PackageTargetRuntime` property.  In the corefx repo we automatically select default values for these properties based on the [Build pivots](#build-pivots).  These can be overridden in the project reference using metadata of the same name, but this is rarely needed.
+Asset projects (`.csproj`, `.vbproj`, or `.depproj`) can control their `{targetMoniker}` using the `PackageTargetFramework` property in the project file.  Similarly `{rid}` is controlled using the `PackageTargetRuntime` property.  For the libraries we automatically select default values for these properties based on the build pivots.  These can be overridden in the project reference using metadata of the same name, but this is rarely needed.
 
 The primary thing that the library author needs to do in order to ensure the correct asset selection is:
 

docs/coding-guidelines/performance-guidelines.md

@@ -5,7 +5,7 @@ Different applications have different needs when it comes to performance.  For l
 
 Much has been written about writing high-performance code in C#.  This page provides links to some of that material and will expand over time as additional resources are found and identified as being relevant and useful.
 
-You can read [CoreCLR Performance Requirements](../../coreclr/project-docs/performance-guidelines.md) to learn more.
+You can read [CoreCLR Performance Requirements](../project/performance-guidelines.md) to learn more.
 
 # Memory Management
 

docs/coding-guidelines/project-guidelines.md

@@ -244,7 +244,8 @@ Each source file should use the following guidelines
   - `.WinRT.cs` - implementation based on [WinRT](https://en.wikipedia.org/wiki/Windows_Runtime)
 
 ## Define naming convention
-As mentioned in [Conventions for forked code](conventions-for-forked-code) `#ifdef`ing the code is the last resort as it makes code harder to maintain overtime. If we do need to use `#ifdef`'s we should use the following conventions:
+
+As mentioned in [Conventions for forked code](#conventions-for-forked-code) `#ifdef`ing the code is the last resort as it makes code harder to maintain overtime. If we do need to use `#ifdef`'s we should use the following conventions:
 - Defines based on conventions should be one of `$(OSGroup)`, `$(TargetGroup)`, `$(ConfigurationGroup)`, or `$(Platform)`, matching exactly by case to ensure consistency.
  - Examples: `<DefineConstants>$(DefineConstants);net46</DefineConstants>`
 - Defines based on convention should match the pattern `FEATURE_<feature name>`. These can unique to a given library project or potentially shared (via name) across multiple projects.

docs/coding-guidelines/updating-ref-source.md

-This document provides the steps you need to take to update the reference assembly when adding new **public** APIs to an implementation assembly (post [API Review](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/adding-api-guidelines.md)).
+This document provides the steps you need to take to update the reference assembly when adding new **public** APIs to an implementation assembly (post [API Review](adding-api-guidelines.md)).
 
-## For most assemblies within corefx
-1) Implement the API in the source assembly and [build it](../project-docs/developer-guide.md#building-individual-libraries).
-2) Run the following command (from the src directory) `msbuild /t:GenerateReferenceSource` to update the reference assembly**.
-3) Navigate to the ref directory and build the reference assembly.
-4) Add, build, and run tests.
+## For most assemblies within libraries
+
+1. Implement the API in the source assembly and [build it](../workflow/building/libraries/README.md#building-individual-libraries).
+2. Run the following command (from the src directory) `msbuild /t:GenerateReferenceSource` to update the reference assembly**.
+3. Navigate to the ref directory and build the reference assembly.
+4. Add, build, and run tests.
 
 ** **Note:** If you already added the new API to the reference source, re-generating it (after building the source assembly) will update it to be fully qualified  and placed in the correct order. This can be done by running the `GenerateReferenceSource` command from the ref directory.
 
 ## For System.Runtime
+
 These steps can also be applied to some unique assemblies which depend on changes in System.Private.Corelib coming from [coreclr](https://github.com/dotnet/coreclr) (partial facades like [System.Memory](https://github.com/dotnet/corefx/blob/83711167ee74d2e87cf2d5ed3508c94044bb7edc/src/System.Memory/src/System.Memory.csproj#L6), for example).
 1) Build coreclr release.
-2) Build corefx release with coreclr bits (see [Testing with private CoreCLR bits](../project-docs/developer-guide.md#testing-with-private-coreclr-bits) for more details).
+2) Build corefx release with coreclr bits (see (// TODO //)) for more details).
 3) Run `msbuild /t:GenerateReferenceSource /p:ConfigurationGroup=Release` from the System.Runtime/ref directory.
-4) Filter out all unrelated changes and extract the changes you care about (ignore certain attributes being removed). Generally, this step is not required for other reference assemblies.
\ No newline at end of file
+4) Filter out all unrelated changes and extract the changes you care about (ignore certain attributes being removed). Generally, this step is not required for other reference assemblies.

docs/design/coreclr/botr/intro-to-clr.md

@@ -254,6 +254,6 @@ Phew!  The runtime does a lot! It has taken many pages just to describe _some_ o
 - [CoreCLR Repo Documentation](README.md)
 
 [clr]: http://msdn.microsoft.com/library/8bs2ecf4.aspx
-[ecma-spec]: ../project-docs/dotnet-standards.md
+[ecma-spec]: ../../../project/dotnet-standards.md
 [cil-spec]: http://download.microsoft.com/download/7/3/3/733AD403-90B2-4064-A81E-01035A7FE13C/MS%20Partition%20III.pdf
 [fx-design-guidelines]: http://msdn.microsoft.com/en-us/library/ms229042.aspx

docs/design/coreclr/botr/method-descriptor.md

@@ -50,11 +50,11 @@ P/Invoke methods. These are methods marked with DllImport attribute.
 
 **EEImpl**
 
-Delegate methods whose implementation is provided by the runtime (Invoke, BeginInvoke, EndInvoke). See [ECMA 335 Partition II - Delegates](../project-docs/dotnet-standards.md).
+Delegate methods whose implementation is provided by the runtime (Invoke, BeginInvoke, EndInvoke). See [ECMA 335 Partition II - Delegates](../../../project/dotnet-standards.md).
 
 **Array**
 
-Array methods whose implementation is provided by the runtime (Get, Set, Address). See [ECMA Partition II – Arrays](../project-docs/dotnet-standards.md).
+Array methods whose implementation is provided by the runtime (Get, Set, Address). See [ECMA Partition II – Arrays](../../../project/dotnet-standards.md).
 
 **ComInterop**
 

docs/design/coreclr/botr/mscorlib.md

@@ -172,7 +172,7 @@ FCalls require a lot of glue, too much to describe here. Look at [fcall.h][fcall
 
 ### GC Holes, FCall, and QCall
 
-A much more complete discussion on GC holes can be found in the [CLR Code Guide](../coding-guidelines/clr-code-guide.md). Look for ["Is your code GC-safe?"](../coding-guidelines/clr-code-guide.md#is-your-code-gc-safe). This tailored discussion motivates some of the reasons why FCall and QCall have some of their strange conventions.
+A much more complete discussion on GC holes can be found in the [CLR Code Guide](../../../coding-guidelines/clr-code-guide.md). Look for ["Is your code GC-safe?"](../../../coding-guidelines/clr-code-guide.md#2.1). This tailored discussion motivates some of the reasons why FCall and QCall have some of their strange conventions.
 
 Object references passed as parameters to FCall methods are not GC-protected, meaning that if a GC occurs, those references will point to the old location in memory of an object, not the new location. For this reason, FCalls usually follow the discipline of accepting something like "StringObject*" as their parameter type, then explicitly converting that to a STRINGREF before doing operations that may trigger a GC. You must GC protect object references before triggering a GC, if you expect to be able to use that object reference later.
 

docs/design/coreclr/botr/porting-ryujit.md

@@ -53,7 +53,7 @@ There are several steps to follow to port the JIT (some of which can be be done
   * `FEATURE_SIMD`
 * Build the new JIT as an altjit. In this mode, a "base" JIT is invoked to compile all functions except
   the one(s) specified by the `COMPlus_AltJit` variable. For example, setting `COMPlus_AltJit=Add` and running
-  a test will use the "base" JIT (say, the Windows x64 targetting JIT) to compile all functions *except*
+  a test will use the "base" JIT (say, the Windows x64 targeting JIT) to compile all functions *except*
   `Add`, which will be first compiled by the new altjit, and if it fails, fall back to the "base" JIT. In this
   way, only very limited JIT functionality need to work, as the "base" JIT takes care of most functions.
 * Implement the basic instruction encodings. Test them using a method like `CodeGen::genArm64EmitterUnitTests()`.

docs/design/coreclr/botr/threading.md

@@ -27,7 +27,7 @@ Every managed thread has an associated Thread object, defined in [threads.h][thr
 
 All Thread objects are stored in the ThreadStore (also defined in [threads.h][threads.h]), which is a simple list of all known Thread objects. To enumerate all managed threads, one must first acquire the ThreadStoreLock, then use ThreadStore::GetAllThreadList to enumerate all Thread objects. This list may include managed threads which are not currently assigned to native threads (for example, they may not yet be started, or the native thread may already have exited).
 
-[threads.h]: ../../src/vm/threads.h
+[threads.h]: ../../../../src/coreclr/src/vm/threads.h
 
 Each managed thread that is currently assigned to a native thread is reachable via a native thread-local storage (TLS) slot on that native thread. This allows code that is executing on that native thread to get the corresponding Thread object, via GetThread().
 
@@ -135,8 +135,8 @@ Sync blocks are stored in the Sync Block Table, and are addressed by sync block
 
 The details of object headers and sync blocks are defined in [syncblk.h][syncblk.h]/[.cpp][syncblk.cpp].
 
-[syncblk.h]: ../../src/vm/syncblk.h
-[syncblk.cpp]: ../../src/vm/syncblk.cpp
+[syncblk.h]: ../../../../src/coreclr/src/vm/syncblk.h
+[syncblk.cpp]: ../../../../src/coreclr/src/vm/syncblk.cpp
 
 If there is room on the object header, Monitor stores the managed thread ID of the thread that currently holds the lock on the object (or zero (0) if no thread holds the lock). Acquiring the lock in this case is a simple matter of spin-waiting until the object header's thread ID is zero, and then atomically setting it to the current thread's managed thread ID.
 
@@ -168,12 +168,12 @@ Thus entering cooperative mode in native code is discouraged. In cases where coo
 
 Similarly, GCX\_PREEMP potentially _releases_ a lock that had been held by the thread. Great care must be taken to ensure that all GC references are properly protected before entering preemptive mode.
 
-The [Rules of the Code](../coding-guidelines/clr-code-guide.md) document describes the disciplines needed to ensure safety around GC mode switches.
+The [Rules of the Code](../../../coding-guidelines/clr-code-guide.md) document describes the disciplines needed to ensure safety around GC mode switches.
 
 Crst
 ----
 
-Just as Monitor is the preferred locking mechanism for managed code, Crst is the preferred mechanism for VM code. Like Monitor, Crst is a hybrid lock that is aware of hosts and GC modes. Crst also implements deadlock avoidance via "lock leveling," described in the [Crst Leveling chapter of the BotR](../coding-guidelines/clr-code-guide.md#264-entering-and-leaving-crsts).
+Just as Monitor is the preferred locking mechanism for managed code, Crst is the preferred mechanism for VM code. Like Monitor, Crst is a hybrid lock that is aware of hosts and GC modes. Crst also implements deadlock avoidance via "lock leveling," described in the [Crst Leveling chapter of the BotR](../../../coding-guidelines/clr-code-guide.md#2.6.4).
 
 It is generally illegal to acquire a Crst while in cooperative mode, though exceptions are made where absolutely necessary.
 

docs/design/coreclr/botr/type-system.md

@@ -227,7 +227,7 @@ Major entry points are BuildMethodTable, LoadTypeHandleThrowing, CanCastTo\*, Ge
 Related Reading
 ===============
 
-- [ECMA CLI Specification](../project-docs/dotnet-standards.md)
+- [ECMA CLI Specification](../../../project/dotnet-standards.md)
 - [Type Loader](type-loader.md) Book of the Runtime Chapter
 - [Virtual Stub Dispatch](virtual-stub-dispatch.md) Book of the Runtime Chapter
 - [MethodDesc](method-descriptor.md) Book of the Runtime Chapter

docs/design/coreclr/profiling/Profiler Breaking Changes.md

@@ -2,6 +2,6 @@
 
 Over time we will need to modify the Profiler APIs, this document will serve as a record of any breaking changes.
 
-1. Code Versioning introduced changes documented [here](../design-docs/code-versioning-profiler-breaking-changes.md)
+1. Code Versioning introduced changes documented [here](../../features/code-versioning-profiler-breaking-changes.md)
 2. The work to allow adding new types and methods after module load means ICorProfilerInfo7::ApplyMetadata will now potentially trigger a GC, and will not be callable in situations where a GC can not happen (for example  ICorProfilerCallback::RootReferences).
 3. As part of the work to allow ReJIT on attach ReJITted methods will no longer be inlined (ever). Since the inlining is blocked there won't be a `ICorProfilerCallback::JITInlining` callback.
\ No newline at end of file

docs/design/features/IJW-activation.md

@@ -19,7 +19,7 @@ IJW applications are much easier in that they are not loaded under the loader-lo
 
 ### .NET Framework IJW Activation
 
-When targetting .NET Framework, mixed mode assemblies are linked to the shim library `mscoree.dll` or `mscoreei.dll`. See the document on [COM Activation](COM-activation.md#.NET-Framework-Class-COM-Activation) for more information on the history of `mscoree.dll` and `mscoreei.dll`. C++/CLI executables are wired up to call `mscoreei.dll`'s `_CorExeMain` method on start which starts the runtime, patching the vtfixup table and calling the managed entry point. If the C++/CLI executable has a native entry point, a managed P/Invoke signature pointing to that native function in the image is emitted into the assembly as the assembly entry point.
+When targeting .NET Framework, mixed mode assemblies are linked to the shim library `mscoree.dll` or `mscoreei.dll`. See the document on [COM Activation](COM-activation.md#NET-Framework-Class-COM-Activation) for more information on the history of `mscoree.dll` and `mscoreei.dll`. C++/CLI executables are wired up to call `mscoreei.dll`'s `_CorExeMain` method on start which starts the runtime, patching the vtfixup table and calling the managed entry point. If the C++/CLI executable has a native entry point, a managed P/Invoke signature pointing to that native function in the image is emitted into the assembly as the assembly entry point.
 
 If the assembly is a library, the library's native initialization function (what calls `DllMain` in a fully native DLL load scenario), calls into `mscoreei.dll`'s `_CorDllMain`. This `_CorDllMain` function patches the vtfixup table to have pointers to stubs that will start the runtime when called. Additionally, the runtime will call back into `mscoree.dll` when patching the vtfixup table with JIT stubs to check if the value in the table is a token or a stub to ensure that it patches the correct JIT stub in place.
 

docs/design/features/code-generation-strategies.md

@@ -8,7 +8,7 @@ One of the most important tasks a .NET runtime has is turning instructions for t
 
 One of the techniques that CoreCLR employs is Just in time compilation ("JIT"). This strategy translates instructions for the abstract processor into native instructions for the processor that the program is running on "just in time". The term "just in time" means that the translation happens when the need arises. For example, a method can be translated when it's first called.
 
-The actual transformation of IL into native code is handled by the code generator. Code generator is a component of the CoreCLR virtual machine that (with the help of other components of CoreCLR, such as the type system) translates IL into native code. The code generator talks to the rest of the virtual machine over a well-defined interface: this allows code generators to be relatively pluggable. The code generator used by the CoreCLR is [RyuJIT](../botr/ryujit-overview.md). Over the years, CLR has had many other code generators serving different purposes, such as the simplified [fjit](https://github.com/SSCLI/sscli20_20060311/tree/master/clr/src/fjit), LLVM-based [LLIC](https://github.com/dotnet/llilc), or the closed-source jit32 and jit64.
+The actual transformation of IL into native code is handled by the code generator. Code generator is a component of the CoreCLR virtual machine that (with the help of other components of CoreCLR, such as the type system) translates IL into native code. The code generator talks to the rest of the virtual machine over a well-defined interface: this allows code generators to be relatively pluggable. The code generator used by the CoreCLR is [RyuJIT](../coreclr/botr/ryujit-overview.md). Over the years, CLR has had many other code generators serving different purposes, such as the simplified [fjit](https://github.com/SSCLI/sscli20_20060311/tree/master/clr/src/fjit), LLVM-based [LLIC](https://github.com/dotnet/llilc), or the closed-source jit32 and jit64.
 
 Big advantage of Just in time compilation is that the generated native code can be tailored for the specific physical processor model. RyuJIT currently uses information about the processor to e.g. unlock the use of AVX instructions on x64 processors that support it.
 
@@ -20,7 +20,7 @@ Another technique to run IL that CoreCLR employs is Ahead of time compilation ("
 
 The code generator used for ahead of time compilation is typically the same one that would be used as a JIT, although it could be a different one if it follows the same ABI.
 
-The format of ahead of time compiled binaries is called [Ready To Run](../botr/readytorun-overview.md) ("R2R"). The format amends the IL with pregenerated native code for a specific operating system and CPU architecture. It preserves the version resiliance of the original IL assemblies.
+The format of ahead of time compiled binaries is called [Ready To Run](../coreclr/botr/readytorun-overview.md) ("R2R"). The format amends the IL with pregenerated native code for a specific operating system and CPU architecture. It preserves the version resiliance of the original IL assemblies.
 
 Ahead of time compilation gives the code generator more time to perform optimizations.
 
@@ -34,4 +34,4 @@ The best results are typically achieved by mixed execution strategies - CoreCLR
 
 ## Tiered compilation
 
-A feature of CoreCLR that spans the whole spectrum of execution strategies is [tiered compilation](tiered-compilation.md). Tiered compilation uses the runtime [profiling](../botr/profiling.md) infrastructure to measure how often particular method runs. When the method appears "hot" (often called), CoreCLR is able to recompile the method with higher optimization settings. This helps with balancing the time it takes to compile the method and the amount of optimizations applied.
+A feature of CoreCLR that spans the whole spectrum of execution strategies is [tiered compilation](tiered-compilation.md). Tiered compilation uses the runtime [profiling](../coreclr/botr/profiling.md) infrastructure to measure how often particular method runs. When the method appears "hot" (often called), CoreCLR is able to recompile the method with higher optimization settings. This helps with balancing the time it takes to compile the method and the amount of optimizations applied.

docs/design/features/code-versioning.md

@@ -158,7 +158,7 @@ Implementation
 
 ### Code Versions ###
 
-The implementation can be located in [codeversion.h](../../src/vm/codeversion.h) and [codeversion.cpp](../../src/vm/codeversion.cpp)
+The implementation can be located in [codeversion.h](../../../src/coreclr/src/vm/codeversion.h) and [codeversion.cpp](../../../src/coreclr/src/vm/codeversion.cpp)
 
 Code versions are embodied by the configuration in NativeCodeVersion structure as well as the configuration in the transitively reachable ILCodeVersion. NativeCodeVersion::GetILCodeVersion() allows trivial access from one part of the configuration to the other. These structures have various accesors to retrieve all the code and configuration data such as:
 

docs/design/features/first-class-structs.md

@@ -256,7 +256,8 @@ This would be enabled first by [Defer ABI-specific transformations to Lowering](
 
   * Related: #11407, #17257
 
-###  <a name="Improve-Struct-Promotion"/>Improve Struct Promotion
+###  Improve Struct Promotion
+
  * Support recursive (nested) struct promotion, especially when struct field itself has a single field
    (#10019, #9594, #7313)
  * Support partial struct promotion when some fields are more frequently accessed.

docs/design/features/lsra-detail.md

@@ -17,7 +17,7 @@ Table of Contents
 
 [LSRA Stress Modes](#lsra-stress-modes)
 
-[Assertions & Validation](#assertions-validation)
+[Assertions & Validation](#assertions--validation)
 
 [Future Extensions and Enhancements](#future-extensions-and-enhancements)
 

docs/design/features/object-stack-allocation.md

@@ -28,7 +28,7 @@ various Java runtimes.  This optimization is more important for Java since it do
 An object is said to escape a method if it can be accessed after the method's execution has finished.
 An object allocation can be moved to the stack safely only if the object doesn't escape the allocating method.
 
-Several escape algorithms have been implemented in different Java implementations. Of the 3 algorithms listed in [references](References),
+Several escape algorithms have been implemented in different Java implementations. Of the 3 algorithms listed in [references](#References),
 [[1]](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.73.4799&rep=rep1&type=pdf)
 is the most precise and most expensive (it is based on connection graphs) and was used in the context of a static Java compiler,
 [[3]](https://pdfs.semanticscholar.org/1b33/dff471644f309392049c2791bca9a7f3b19c.pdf)

docs/design/features/tiered-compilation.md

@@ -82,11 +82,11 @@ Despite the anticipated shortcomings, the 2.1 RTM policy is a surprisingly decen
 Implementation
 ==============
 
-The majority of the implementation can be located in [tieredcompilation.h](../../src/vm/tieredcompilation.h), and [tieredcompilation.cpp](../../src/vm/tieredcompilation.cpp)
+The majority of the implementation can be located in [tieredcompilation.h](../../../src/coreclr/src/vm/tieredcompilation.h), and [tieredcompilation.cpp](../../../src/coreclr/src/vm/tieredcompilation.cpp)
 
-The call counter is implemented in [callcounter.h](../../src/vm/callcounter.h), and [callcounter.cpp](../../src/vm/callcounter.cpp)
+The call counter is implemented in [callcounter.h](../../../src/coreclr/src/vm/callcounter.h), and [callcounter.cpp](../../../src/coreclr/src/vm/callcounter.cpp)
 
-The policy that determines which methods are eligible for tiering is implemented in `MethodDesc::IsEligibleForTieredCompilation`, located in [method.hpp](../../src/vm/method.hpp)
+The policy that determines which methods are eligible for tiering is implemented in `MethodDesc::IsEligibleForTieredCompilation`, located in [method.hpp](../../../src/coreclr/src/vm/method.hpp)
 
 Most of the implementation is relatively straightforward given the design and best described by reading the code, but a few notes:
 

docs/design/features/variabletracking.md

@@ -11,15 +11,15 @@ Table of Contents
 
 [Debug Code vs Optimized Code](#debug-code-vs-optimized-code)
 
-[siScope / psiScope Structures](#siscope-psiscope-structure)
+[siScope / psiScope Structures](#siscope--psiscope-structures)
 
-[Generating siScope / psiScope info](#siscope-psiscope)
+[Generating siScope / psiScope info](#Generating-siscope--psiscope-info)
 
-[Variable Live Range Structure](#variable-live-range-structure)
+[Variable Live Range Structure](#variableliverange)
 
-[Generating Variable Live Range](#variable-live-range)
+[Generating Variable Live Range](#Generating-Variable-Live-Range)
 
-[Turning On Debug Info](#debug-indo-flags)
+[Turning On Debug Info](#turning-on-debug-info)
 
 [Dumps and Debugging Support](#dumps-and-debugging-support)
 

docs/project/glossary.md

@@ -32,7 +32,7 @@ terminology.
 | PGO | Profile Guided Optimization - see [details](https://blogs.msdn.microsoft.com/vcblog/2008/11/12/pogo/). |
 | POGO | Profile Guided Optimization - see [details](https://blogs.msdn.microsoft.com/vcblog/2008/11/12/pogo/). |
 | ProjectN | Codename for the first version of [.NET Native for UWP](https://msdn.microsoft.com/en-us/vstudio/dotnetnative.aspx). |
-| R2R | Ready-to-Run. A flavor of native images - command line switch of [crossgen](../building/crossgen.md). |
+| R2R | Ready-to-Run. A flavor of native images - command line switch of [crossgen](../workflow/building/coreclr/crossgen.md). |
 | Redhawk | Codename for experimental minimal managed code runtime that evolved into [CoreRT](https://github.com/dotnet/corert/). |
 | SOS | [Son of Strike](http://blogs.msdn.com/b/jasonz/archive/2003/10/21/53581.aspx). The debugging extension for DbgEng based debuggers. Uses the DAC as an abstraction layer for its operation. |
 | SuperPMI | JIT component test framework (super fast JIT testing - it mocks/replays EE in EE-JIT interface) - see [SuperPMI details](https://github.com/dotnet/coreclr/blob/master/src/ToolBox/superpmi/readme.txt). |
@@ -41,7 +41,7 @@ terminology.
 | URT | Universal Runtime. Ancient name for what ended up being .NET, is used in the WinError facility name FACILITY_URT. |
 | UTC | [Universal Tuple Compiler](https://blogs.msdn.microsoft.com/vcblog/2013/06/12/optimizing-c-code-overview/). The Microsoft C++ optimizer back-end that that starts by converting the information from the FrontEnd into tuples – a binary stream of instructions. |
 | UWP | [Universal Windows Platform (UWP)](https://docs.microsoft.com/en-us/windows/uwp/get-started/universal-application-platform-guide) is a platform-homogeneous application architecture available on every device that runs Windows 10. |
-| VSD | [Virtual Stub Dispatch](../botr/virtual-stub-dispatch.md). Technique of using stubs for virtual method invocations instead of the traditional virtual method table. |
+| VSD | [Virtual Stub Dispatch](../design/coreclr/botr/virtual-stub-dispatch.md). Technique of using stubs for virtual method invocations instead of the traditional virtual method table. |
 | VM | Virtual machine. |
 | WKS | The CLR used to be built as two variants, with one called "mscorwks.dll", to mean the "workstation" version. In particular, it contained the client GC implementation, which was intended for single-threaded apps, independent of how many processors were on the machine. In the .NET Framework 2 release, the two variants were merged into "mscorwks.dll". The WKS version was the default, however the SVR version remained available. |
 | ZAP | Original code name for NGen. |

docs/project/performance-guidelines.md

@@ -3,7 +3,7 @@ Performance Requirements
 
 The .NET runtime supports a wide variety of high performance applications.  As such, performance is a key design element for every change.  This guidance is designed to share how we collect data and analyze the performance of the runtime.
 
-You may also want to read about [CoreFX performance guidelines](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/performance-guidelines.md).
+You may also want to read about [performance coding guidelines](../coding-guidelines/performance-guidelines.md).
 
 # Design Phase #
 Make sure to address performance during the design phase of any change.  It is much easier to tweak a design to fit performance goals and requirements before implementation has started.

docs/workflow/README.md

 # Workflow Guide
 
-The repo can be built for the following platforms, using the provided setup and the following instructions.
+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.
 
 | Chip  | Windows  | Linux    | macOS    | FreeBSD  |
 | :---- | :------: | :------: | :------: | :------: |
@@ -8,13 +8,13 @@ The repo can be built for the following platforms, using the provided setup and
 | x86   | ✔ |          |          |          |
 | ARM   | ✔ | ✔ |          |          |
 | ARM64 | ✔ | ✔ |          |          |
-|       | [Requirements](windows-requirements.md) | [Requirements](linux-requirements.md) | [Requirements](macos-instructions.md) |
+|       | [Requirements](requirements/windows-requirements.md) | [Requirements](requirements/linux-requirements.md) | [Requirements](requirements/macos-requirements.md) |
 
-## Building the repository
+## 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.
 
-For information about the different options available, suplly the argument `-help|-h` when invoking the build script:
+For information about the different options available, supply the argument `-help|-h` when invoking the build script:
 ```
 libraries -h
 ```
@@ -22,4 +22,10 @@ On Unix, arguments can be passed in with a single `-` or double hyphen `--`.
 
 ## Workflows
 
-For instructions on how to build, debug, test, etc. please visit the instructions in the workflow sub-folders.
\ No newline at end of file
+For instructions on how to build, debug, test, etc. please visit the instructions in the workflow sub-folders.
+
+- [Building coreclr](building/coreclr/README.md)
+- [Building libraries](building/libraries/README.md)
+
+- [Testing coreclr](testing/coreclr/testing.md)
+- [Testing libraries](testing/libraries/testing.md)
\ No newline at end of file

docs/workflow/building/coreclr/README.md

@@ -31,4 +31,4 @@ The build has a number of options that you can learn about using build -?.   Som
  * -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.
 
-See [Running Tests](../../testing/coreclr-testing.md) for instructions on running the tests.
+See [Running Tests](../../testing/coreclr/testing.md) for instructions on running the tests.

docs/workflow/building/coreclr/cross-building.md

@@ -21,7 +21,7 @@ Cross Compilation for ARM, ARM64 or x86 on Linux
 
 Through cross compilation, on Linux it is possible to build CoreCLR for arm or arm64. Note that this documentation exists to explain using `runtime/eng/common/build-rootfs.sh`. This will build a rootfs and then use it to cross build. Newer documentation [linux-instructions.md](linux-instructions.md) exists which leverages docker to use a prebuilt environment to cross build.
 
-Requirements for targetting Debian based distros
+Requirements for targeting Debian based distros
 ------------------------------------------------
 
 You need a Debian based host and the following packages need to be installed:
@@ -41,7 +41,7 @@ and for armel (ARM softfp):
     ~/runtime/ $ sudo apt-get install binutils-arm-linux-gnueabi
 
 
-Requirements for targetting ARM or ARM64 Alpine Linux
+Requirements for targeting ARM or ARM64 Alpine Linux
 -----------------------------------------------------
 
 You can use any Linux distro as a host. The qemu, qemu-user-static and binfmt-support packages need to be installed (the names may be different for some distros).

docs/workflow/building/libraries/code-coverage.md

@@ -58,6 +58,6 @@ Some of the libraries for which contracts and tests live in the corefx repo are
 
 If the test project does not set the property `TestRuntime` to `true` and you want to collect code coverage that includes types in System.Private.CoreLib.dll add `/p:TestRuntime=true` to the coverage build command listed above.
 
-If you want to get coverage report against a private build of System.Private.CoreLib follow the steps outlined at [Testing with Private CoreClr Bits](../project-docs/developer-guide.md#testing-with-private-coreclr-bits).
+If you want to get coverage report against a private build of System.Private.CoreLib (// TODO //).
 
 The build and test projects take care of copying assemblies and PDBs as needed for coverage runs. The resulting code coverage report should now also include details for System.Private.CoreLib.

docs/workflow/debugging/crash-dumps.md

@@ -13,4 +13,4 @@ The crash dump can then be located via this unique identifier from the Dumpling
 
 Note that, while Dumpling archives the crash dumps for a long time, the Jenkins CI logs (containing the test info and the crash dump identifier) are not persisted for more than a few days.
 
-Debugging crash dumps is a fairly involved process. Windows crash dumps are well-supported using existing and documented tools like Visual Studio, WinDBG, and SOS. The instructions for Unix platforms are complicated, and are documented [here](../debugging/unix-instructions.md#debugging-core-dumps-with-lldb).
+Debugging crash dumps is a fairly involved process. Windows crash dumps are well-supported using existing and documented tools like Visual Studio, WinDBG, and SOS. The instructions for Unix platforms are complicated, and are documented [here](../debugging/coreclr/debugging.md#debugging-core-dumps-with-lldb).

docs/workflow/debugging/debugging-packages.md → docs/workflow/debugging/libraries/debugging-packages.md

@@ -16,7 +16,7 @@ Debugging CoreFX build issues
 
 I found the following process to help when investigating some of the build issues caused by incorrect packaging. 
 
-To quickly validate if a given project compiles on all supported configurations use `dotnet msbuild /t:RebuildAll`. This applies for running tests as well. For more information, see [Building individual libraries](../project-docs/developer-guide.md#building-individual-libraries) 
+To quickly validate if a given project compiles on all supported configurations use `dotnet msbuild /t:RebuildAll`. This applies for running tests as well. For more information, see [Building individual libraries](../../building/libraries/README.md#building-individual-libraries) 
 
 Assuming the current directory is `\src\contractname\`:
 

docs/workflow/debugging/unix-instructions.md → docs/workflow/debugging/libraries/unix-instructions.md

@@ -6,7 +6,7 @@ CoreFX can be debugged on unix using both lldb and visual studio code
 ## Using lldb and SOS
 
 - Run the test using msbuild at least once with `/t:BuildAndTest`.
-- [Install version 3.9 of lldb](../../coreclr/building/debugging-instructions.md#debugging-core-dumps-with-lldb) and launch lldb with dotnet as the process and arguments matching the arguments used when running the test through msbuild.
+- [Install version 3.9 of lldb](../coreclr/debugging.md#debugging-core-dumps-with-lldb) and launch lldb with dotnet as the process and arguments matching the arguments used when running the test through msbuild.
 - Load the sos plugin using `plugin load libsosplugin.so`.
 - Type `soshelp` to get help. You can now use all sos commands like `bpmd`.
 
@@ -29,7 +29,7 @@ It is also possible to debug .NET Core crash dumps using lldb and SOS. In order
 2017-10-10 21:17:48,020: INFO: proc(54): run_and_log_output: Output: <b>https://dumpling.azurewebsites.net/api/dumplings/archived/eefcb1cc36977ccf86f457ee28a33a7b4cc24e13</b>
 </pre>
 - The crash dump file. We have a service called "Dumpling" which collects, uploads, and archives crash dump files during all of our CI jobs and official builds.
-- On Linux, there is an utility called `createdump` (see [doc](../../coreclr/botr/xplat-minidump-generation.md "doc")) that can be setup to generate core dumps when a managed app throws an unhandled exception or faults.
+- On Linux, there is an utility called `createdump` (see [doc](../../../design/coreclr/botr/xplat-minidump-generation.md "doc")) that can be setup to generate core dumps when a managed app throws an unhandled exception or faults.
 - Matching coreclr/corefx runtime bits from the crash. To get these, you should either:
   - Download the matching Jenkins archive onto your repro machine.
   - Check out the coreclr and corefx repositories at the appropriate commit and re-build the necessary portions.
@@ -54,6 +54,8 @@ lldb-3.9 -O "settings set target.exec-search-paths <runtime-path>" -o "plugin lo
 
 lldb should start debugging successfully at this point. You should see stacktraces with resolved symbols for libcoreclr.so. At this point, you can run `plugin load <libsosplugin.so-path>`, and begin using SOS commands, as above.
 
+Also see this [link](https://github.com/dotnet/diagnostics/blob/master/documentation/debugging-coredump.md) in the diagnostics repo.
+
 ##### Example
 
 ```

docs/workflow/debugging/windows-instructions.md → docs/workflow/debugging/libraries/windows-instructions.md

@@ -3,7 +3,7 @@ Debugging CoreFX on Windows
 
 You can Debug .NET Core via Visual Studio or WinDBG.
 
-For Visual Studio debugging, follow the instructions at [Debugging tests in Visual Studio](../building/windows-instructions.md) to run and debug tests.
+For Visual Studio debugging, follow the instructions at [Debugging tests in Visual Studio](../../testing/libraries/testing-vs.md) to run and debug tests.
 For bugs that cannot be reproduced within Visual Studio (certain low-probability race conditions, SafeHandle life-time problems, etc) you will need to use WinDBG.
 
 ## Required Software

docs/workflow/EditingAndDebugging.md → docs/workflow/editing-and-debugging.md

@@ -34,7 +34,7 @@ to do most editing.
 Notice that the CoreCLR solution is under the 'bin' directory.  This is because it is created as part of the build.
 Thus you can only launch this solution after you have built at least once.
 
-* See [Debugging](debugging/debugging-instructions.md)
+* See [Debugging CoreCLR](debugging/coreclr/debugging.md)
 
 # See Also
 

docs/workflow/linux-requirements.md → docs/workflow/requirements/linux-requirements.md

@@ -41,7 +41,7 @@ Note that instructions on building the crossrootfs location can be found at http
 Docker Images
 =============
 
-These instructions might fall stale often enough as we change our images as our requirements change. The table below is just a quick reference view of the images we use in different build scenarios. The ones that we use for our our official builds can be found in [the platform matrix](../../eng/pipelines/common/platform-matrix.yml) of our Azure DevOps builds under the `container` key of the platform you plan to build.
+These instructions might fall stale often enough as we change our images as our requirements change. The table below is just a quick reference view of the images we use in different build scenarios. The ones that we use for our our official builds can be found in [the platform matrix](../../../eng/pipelines/common/platform-matrix.yml) of our Azure DevOps builds under the `container` key of the platform you plan to build.
 
 | OS                             | Target Arch     | Image location                                                                                       | crossrootfs location |
 | ------------------------------ | --------------- | ---------------------------------------------------------------------------------------------------- | -------------------- |

docs/workflow/windows-requirements.md → docs/workflow/requirements/windows-requirements.md

@@ -68,7 +68,7 @@ The dotnet/runtime repository requires at least Git 2.22.0.
 ## DotNet Core SDK
 
 While not strictly needed to build or test the .NET Core repository, having the .NET Core SDK installed lets you use the dotnet.exe command to run .NET Core applications in the 'normal' way.   We use this in the
-[Using Your Build](./testing/UsingYourBuild.md) instructions.  Visual Studio should have
+[Using Your Build](../testing/using-your-build.md) instructions.  Visual Studio should have
 installed the .NET Core SDK, but in case it did not you can get it from the [Installing the .NET Core SDK](https://dotnet.microsoft.com/download) page.
 
 ## Adding to the default PATH variable

docs/workflow/testing/coreclr-testing.md → docs/workflow/testing/coreclr/testing.md

 # Running .NET Core Tests
 
-Details on test metadata can be found in [test-configuration.md](building/test-configuration.md).
+Details on test metadata can be found in [test-configuration.md](test-configuration.md).
 
 ## Build All Tests
 
 1) Build the CoreCLR product
-    * [Unix](https://github.com/dotnet/runtime/blob/master/docs/coreclr/building/linux-instructions.md)
-    * [OSX](https://github.com/dotnet/runtime/blob/master/docs/coreclr/building/osx-instructions.md)
-    * [Windows](https://github.com/dotnet/runtime/blob/master/docs/coreclr/building/windows-instructions.md)
+    * [Unix](../../building/coreclr/linux-instructions.md)
+    * [OSX](../../building/coreclr/osx-instructions.md)
+    * [Windows](../../building/coreclr/README.md)
 1) From the root directory run the following command:
     * Non-Windows - `./build-test.sh`
     * Windows - `build-test.cmd`
@@ -36,5 +36,5 @@ Note:  CoreCLR must be built prior to building an individual test. See first ste
 
 ## Additional Documents
 
-* [Windows](https://github.com/dotnet/runtime/blob/master/docs/coreclr/building/windows-test-instructions.md)
-* [Non-Windows](https://github.com/dotnet/runtime/blob/master/docs/coreclr/building/unix-test-instructions.md)
+* [Windows](../../testing/coreclr/windows-test-instructions.md)
+* [Non-Windows](../../testing/coreclr/unix-test-instructions.md)

docs/workflow/testing/UsingCoreRun.md → docs/workflow/testing/using-corerun.md

 
 # Using corerun To Run .NET Core Application
 
-In page [Using your .NET Core Runtime Build with dotnet cli](../UsingDotNetCli.md) gives detailed instructions on using the standard
+In page [Using your .NET Core Runtime Build with dotnet cli](../using-dotnet-cli.md) gives detailed instructions on using the standard
 command line host and SDK, dotnet.exe to run a .NET application with the modified build of the
 .NET Core runtime built here.   This is the preferred mechanism for you to officially deploy
 your changes to other people since dotnet.exe and Nuget insure that you end up with a consistent

docs/workflow/testing/UsingYourBuild.md → docs/workflow/testing/using-your-build.md

@@ -20,7 +20,7 @@ assume use of a dogfood build of the .NET SDK.
 - [macOS 64-bit Latest](https://dotnetcli.blob.core.windows.net/dotnet/Sdk/master/dotnet-sdk-latest-osx-x64.tar.gz)
 - [Others](https://github.com/dotnet/cli/blob/master/README.md#installers-and-binaries)
 
-To setup the SDK download the zip and extract it somewhere and add the root folder to your [path](../building/windows-instructions.md#adding-to-the-default-path-variable)
+To setup the SDK download the zip and extract it somewhere and add the root folder to your [path](../requirements/windows-requirements.md#adding-to-the-default-path-variable)
 or always fully qualify the path to dotnet in the root of this folder for all the instructions in this document.
 
 After setting up dotnet you can verify you are using the newer version by:
@@ -156,7 +156,7 @@ Assert failure(PID 13452 [0x0000348c], Thread: 10784 [0x2a20]): Consistency chec
 
 ## Using DotNetCli to run your .NET Core Application
 
-If you don't like the idea of copying files manually you can follow [these instructions](../UsingDotNetCli.md) to use dotnet cli to do this for you.
+If you don't like the idea of copying files manually you can follow [these instructions](../using-dotnet-cli.md) to use dotnet cli to do this for you.
 However the steps described here are the simplest and most commonly used by CoreCLR developers for ad-hoc testing.
 
 ## Using CoreRun to run your .NET Core Application
@@ -165,4 +165,4 @@ Generally using dotnet.exe tool to run your .NET Core application is the preferr
 However there is a simpler 'host' for .NET Core applications called 'CoreRun' that can also be used.   The value
 of this host is that it is simpler (in particular it knows nothing about NuGet), but precisely because of this
 it can be harder to use (since you are responsible for insuring all the dependencies you need are gather together)
-See [Using CoreRun To Run .NET Core Application](UsingCoreRun.md) for more.
+See [Using CoreRun To Run .NET Core Application](using-corerun.md) for more.

docs/workflow/UsingDotNetCli.md → docs/workflow/using-dotnet-cli.md

@@ -5,8 +5,8 @@ This walkthrough explains how to run against your local CoreCLR build using `dot
 
 For other walkthroughs see:
 
-- [Using Your Build - Update CoreCLR from raw binary output](./testing/UsingYourBuild.md)
-- [Using CoreRun To Run .NET Core Application](./testing/UsingCoreRun.md)
+- [Using Your Build - Update CoreCLR from raw binary output](./testing/using-your-build.md)
+- [Using CoreRun To Run .NET Core Application](./testing/using-corerun.md)
 - [Dogfooding .NET Core SDK](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/dogfooding.md).
 
 ## Prerequisites
@@ -17,7 +17,7 @@ For other walkthroughs see:
     artifacts\bin\coreclr\<OS>.<arch>.<flavor>\.nuget\pkg\runtime.<OS>-<arch>.Microsoft.NETCore.Runtime.CoreCLR.<version>.nupkg
 ```
 
-2. Acquired the latest nightly .NET Core SDK from [here](https://github.com/dotnet/cli/blob/master/README.md#installers-and-binaries) and added it's root folder to your [path](./debugging/windows-instructions.md#adding-to-the-default-path-variable)
+2. Acquired the latest nightly .NET Core SDK from [here](https://github.com/dotnet/cli/blob/master/README.md#installers-and-binaries) and added it's root folder to your [path](requirements/windows-requirements.md#adding-to-the-default-path-variable)
 
 ## First Run
 

src/libraries/System.DirectoryServices.AccountManagement/src/Resources/Strings.resx

@@ -156,7 +156,7 @@
     <value>Unpersisted Principal objects can not be deleted.</value>
   </data>
   <data name="PrincipalDeleted" xml:space="preserve">
-    <value>Can�t delete an already deleted object</value>
+    <value>Cannot delete an already deleted object</value>
   </data>
   <data name="PrincipalNotSupportedOnFakePrincipal" xml:space="preserve">
     <value>This Principal object represents a well-known SID and does not correspond to an actual store object.  This operation is not supported on it.</value>