Organize some markdowns and fix links (dotnet#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: Youssef Victor <[email protected]>

* Update docs/coding-guidelines/package-projects.md

Co-Authored-By: Jan Kotas <[email protected]>

Co-authored-by: Youssef Victor <[email protected]>
Co-authored-by: Jan Kotas <[email protected]>

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,14 +6,14 @@ 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
 
 
 # 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
+[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

@@ -1,16 +1,18 @@
-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.
+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.