Skip to content
This repository has been archived by the owner on Jan 23, 2023. It is now read-only.

Update documentation for changing CoreLib #21201

Merged
merged 2 commits into from
Nov 27, 2018
Merged

Update documentation for changing CoreLib #21201

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9bf1820
Update documentation for changing CoreLib
jkotas Nov 26, 2018
0c5f907
CR feedback
jkotas Nov 26, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Documentation/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
29 changes: 0 additions & 29 deletions Documentation/project-docs/adding_new_public_apis.md
View file
Open in desktop

This file was deleted.

22 changes: 22 additions & 0 deletions Documentation/project-docs/changing-corelib.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
danmoseley marked this conversation as resolved.
Show resolved Hide resolved
- 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
Copy link
Member

@ahsonkhan ahsonkhan Nov 26, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we mention the automatic source mirroring that happens?

i.e. something like this:
dotnet/corefx#33687 (comment)

- 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.
11 changes: 3 additions & 8 deletions Documentation/project-docs/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
---------------
Expand Down