Documentation/project-docs/adding_new_public_apis.md

   1 Adding new public APIs to System.Private.CoreLib
   2 ================================================
   3
   4 Many of the CoreFX libraries type-forward their public APIs to the implementations in System.Private.CoreLib.
   5 - The CoreFX build uses System.Private.CoreLib via Microsoft.TargetingPack.Private.CoreCLR Nuget package.
   6 - 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.
   7 - 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.
   8
   9 **Staging the changes**
  10
  11 Make the changes to CoreCLR, including System.Private.CoreLib
  12 - Merge the changes
  13 - 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).
  14
  15 Make the changes to CoreFX consuming the new APIs in System.Private.CoreLib
  16 - If the changes are to libraries that are built out of the CoreFX repository:
  17   - You will likely see a build failure until a new System.Private.CoreLib contract is published
  18 - If the changes are to libraries that are **not** built out of the CoreFX repository:
  19   - For example, pure facades such as System.Runtime.Loader.dll
  20   - There will likely not be a build failure
  21   - 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
  22 - Merge the changes
  23 - Wait for new contracts to be published for libraries with new APIs. Check the latest published versions [here](http://myget.org/gallery/dotnet-core).
  24
  25 Add tests
  26 - You should now be able to consume the new APIs and add tests to the CoreFX test suite
  27   - Until new contracts are published, you will likely see a build failure indicating that the new APIs don't exist.
  28 - Note that on Windows, CoreFX tests currently use a potentially old published build of CoreCLR
  29   - You may need to disable the new tests on Windows until CoreFX tests are updated to use a newer build of CoreCLR.