Update documentation for changing CoreLib (#21201)

4 files changed, 26 insertions, 38 deletions

diff --git a/Documentation/README.md b/Documentation/README.md
index 5438d75bb7..7053c8f7c3 100644
--- a/Documentation/README.md
+++ b/Documentation/README.md
@@ -23,7 +23,7 @@ Project Docs
 - [Contributing Workflow](project-docs/contributing-workflow.md)
 - [Performance Guidelines](project-docs/performance-guidelines.md)
 - [Garbage Collector Guidelines](project-docs/garbage-collector-guidelines.md)
-- [Adding new public APIs to mscorlib](project-docs/adding_new_public_apis.md)
+- [Public APIs in System.Private.CoreLib](project-docs/changing-corelib.md)
 - [Project NuGet Dependencies](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/project-nuget-dependencies.md)
 
 Coding Guidelines
diff --git a/Documentation/project-docs/adding_new_public_apis.md b/Documentation/project-docs/adding_new_public_apis.md
deleted file mode 100644
index cca5095078..0000000000
--- a/Documentation/project-docs/adding_new_public_apis.md
+++ /dev/null
@@ -1,29 +0,0 @@
-Adding new public APIs to System.Private.CoreLib
-================================================
-
-Many of the CoreFX libraries type-forward their public APIs to the implementations in System.Private.CoreLib.
-- The CoreFX build uses System.Private.CoreLib via Microsoft.TargetingPack.Private.CoreCLR Nuget package.
-- Some of the CoreFX libraries are not built in the CoreFX repository. For example, System.Runtime.Loader.dll is purely a facade and type-forwards everything to System.Private.CoreLib. These libraries are built and published through a separate process.
-- Hence, when adding a new public API to System.Private.CoreLib, changes must be staged to ensure that new prerequisites are published before they are used.
-
-**Staging the changes**
-
-Make the changes to CoreCLR, including System.Private.CoreLib
-- Merge the changes
-- Wait for a new System.Private.CoreLib to be published. Check the latest published version [here](https://dotnet.myget.org/feed/dotnet-core/package/nuget/Microsoft.TargetingPack.Private.CoreCLR).
-
-Make the changes to CoreFX consuming the new APIs in System.Private.CoreLib
-- If the changes are to libraries that are built out of the CoreFX repository:
-  - You will likely see a build failure until a new System.Private.CoreLib contract is published
-- If the changes are to libraries that are **not** built out of the CoreFX repository:
-  - For example, pure facades such as System.Runtime.Loader.dll
-  - There will likely not be a build failure
-  - But you will still need to wait for the new System.Private.CoreLib contract to be published before merging the change, otherwise, facade generation will fail
-- Merge the changes
-- Wait for new contracts to be published for libraries with new APIs. Check the latest published versions [here](http://myget.org/gallery/dotnet-core).
-
-Add tests
-- You should now be able to consume the new APIs and add tests to the CoreFX test suite
-  - Until new contracts are published, you will likely see a build failure indicating that the new APIs don't exist.
-- Note that on Windows, CoreFX tests currently use a potentially old published build of CoreCLR
-  - You may need to disable the new tests on Windows until CoreFX tests are updated to use a newer build of CoreCLR.
diff --git a/Documentation/project-docs/changing-corelib.md b/Documentation/project-docs/changing-corelib.md
new file mode 100644
index 0000000000..8ca9f98095
--- /dev/null
+++ b/Documentation/project-docs/changing-corelib.md
@@ -0,0 +1,22 @@
+Changing or adding new public APIs to System.Private.CoreLib
+============================================================
+
+Many of the CoreFX libraries type-forward their public APIs to the implementations in System.Private.CoreLib.
+- The CoreFX build uses System.Private.CoreLib via Microsoft.TargetingPack.Private.CoreCLR Nuget package.
+- Some of the CoreFX libraries are not built in the CoreFX repository. For example, System.Runtime.Loader.dll is purely a facade and type-forwards everything to System.Private.CoreLib. These libraries are built and published through a separate process.
+- Hence, when adding a new public API to System.Private.CoreLib or changing the behavior of the existing public APIs in System.Private.CoreLib, changes must be staged to ensure that new prerequisites are published before they are used.
+
+**Staging the changes**
+
+Make the changes in both CoreCLR and CoreFX
+- System.Private.CoreLib implementation changes should should be made in CoreCLR repo
+- Test and public API contract changes should be made in CoreFX repo
+- [Build and test](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/developer-guide.md#testing-with-private-coreclr-bits) both changes together
+
+Submit PR to both CoreCLR and CoreFX
+- Link the two PRs together via comment in PR description
+- Both PRs will reviewed together by the project maintainers
+- CoreFX tests run on CoreCLR PRs are using old published build. You may need to disable the outdated tests in https://github.com/dotnet/coreclr/blob/master/tests/CoreFX/CoreFX.issues.json to make your PR green.
+- CoreCLR PR will be merged first
+- If your change is under [System.Private.CoreLib Shared Sources](https://github.com/dotnet/coreclr/tree/master/src/System.Private.CoreLib/shared), it will get mirrored to other repos that are reusing the CoreLib sources.
+- Once updated CoreCLR is consumed by CoreFX repo, CoreFX PR will be merged second.
diff --git a/Documentation/project-docs/contributing.md b/Documentation/project-docs/contributing.md
index 12de0145dd..d18a79d08b 100644
--- a/Documentation/project-docs/contributing.md
+++ b/Documentation/project-docs/contributing.md
@@ -61,15 +61,10 @@ Managed Code Compatibility
 
 Contributions must maintain [API signature](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/breaking-changes.md#bucket-1-public-contract) and behavioral compatibility. Contributions that include [breaking changes](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/breaking-changes.md) will be rejected. Please file an issue to discuss your idea or change if you believe that it may affect managed code compatibility.
 
-Contributing to mscorlib library
---------------------------------
+Contributing to System.Private.CoreLib library
+----------------------------------------------
 
-Most managed code changes should be made in the [CoreFX](https://github.com/dotnet/corefx) repo. We have moved and are continuing to move many mscorlib types to CoreFX. Please use the following general rule-of-thumb for choosing the right repo to make your change (start by creating an issue):
-
-- The type or concept doesn't yet exist in .NET Core -> choose CoreFX.
-- The type exists in both CoreCLR and CoreFX repo -> choose CoreFX.
-- The type exists in CoreCLR only -> choose CoreCLR.
-- In doubt -> choose CoreFX.
+Most changes in managed libraries should be made in the [CoreFX](https://github.com/dotnet/corefx) repo. The CoreCLR repo contains implementation for the [System.Private.CoreLib.dll](https://github.com/dotnet/coreclr/tree/master/src/System.Private.CoreLib) library. Publicly visible changes in this library require [staging](changing-corelib.md) over the two repos.
 
 Commit Messages
 ---------------