The .NET Core team maintains several guidelines for contributing to the .NET Core repos, which are provided below. Many of these are straightforward, while others may seem subjective. A .NET Core team member will be happy to explain why a guideline is defined as it is.
- Copyright describes the licensing practices for the project.
- General Contribution Guidance describes general contribution guidance, including more subjective stylistic guidelines.
- Contribution Bar describes the bar that the team uses to accept changes.
- Contribution Workflow describes the workflow that the team uses for considering and accepting changes.
- Garbage Collection Guidelines for changes that affect the GC.
- Performance Guidelines for changes in performance critical code or that otherwise affect performance.
- Porting the JIT to other chip architectures.
There are several issues to keep in mind when making a change.
Please review Breaking Changes before making changes to managed code. Please pay the most attention to changes that affect the Public Contract.
Typos are embarrassing! We will accept most PRs that fix typos. In order to make it easier to review your PR, please focus on a given component with your fixes or on one type of typo across the entire repository. If it's going to take >30 mins to review your PR, then we will probably ask you to chunk it up.
Please format commit messages as follows (based on this excellent post):
Summarize change in 50 characters or less
Provide more detail after the first line. Leave one blank line below the
summary and wrap all lines at 72 characters or less.
If the change fixes an issue, leave another blank line after the final
paragraph and indicate which issue is fixed in the specific format
below.
Fix #42
Also do your best to factor commits appropriately, i.e not too large with unrelated things in the same commit, and not too small with the same small change applied N times in N different commits. If there was some accidental reformatting or whitespace changes during the course of your commits, please rebase them away before submitting the PR.
-
DO follow our coding style (C# code-specific)
-
DO give priority to the current style of the project or file you're changing even if it diverges from the general guidelines.
-
DO include tests when adding new features. When fixing bugs, start with adding a test that highlights how the current behavior is broken.
-
DO keep the discussions focused. When a new or related topic comes up it's often better to create new issue than to side track the discussion.
-
DO blog and tweet (or whatever) about your contributions, frequently!
-
DO NOT send PRs for style changes.
-
DON'T surprise us with big pull requests. Instead, file an issue and start a discussion so we can agree on a direction before you invest a large amount of time.
-
DON'T commit code that you didn't write. If you find code that you think is a good fit to add to .NET Core, file an issue and start a discussion before proceeding.
-
DON'T submit PRs that alter licensing related files or headers. If you believe there's a problem with them, file an issue and we'll be happy to discuss it.
-
DON'T add API additions without filing an issue and discussing with us first. See API Review Process.
Project maintainers will merge changes that align with project priorities and/or improve the product significantly for a broad set of apps. Proposals must also satisfy the published guidelines for .NET Core.
Maintainers will not merge changes that have narrowly-defined benefits, due to compatibility risk. The CoreCLR codebase is used by several Microsoft products (e.g. Windows Phone, ASP.NET Core, .NET Framework 4.x) to enable execution of managed code. Changes to the open source codebase can become part of these products, but are first reviewed and tested to ensure they are correct for those products and will not inadvertently break applications. We may revert changes if they are found to be breaking.
We encourage ports of CoreCLR to other platforms. Linux and OS X ports are in progress and have a lot of momentum behind them. There is also interest in a FreeBSD port (and OpenBSD and NetBSD).
Ports have a weaker contribution bar, since they do not contribute to compatibility risk with existing Microsoft products on Windows. For ports, we are primarily looking for functionally correct implementations.
Most managed code changes should be made in the 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.
Please see Breaking Changes to understand our requirements on changes that could impact compatibility. Please pay the most attention to changes that affect the Public Contract. We will not accept changes that break compatibility.
The .NET Core copyright is held by ".NET Foundation and Contributors". See .NET Foundation.
The .NET Core project uses multiple licenses for the various project repositories. Most projects use the MIT License for code and the Creative Commons Attribution 4.0 International Public License (CC-BY) license for documentation. The Apache 2 License is also used.
See the license file at the root of project repositories for the specific license, such as with the following examples:
Microsoft produces a distribution of .NET Core licensed under the .NET Library License. Other groups or companies may produce their own distributions of .NET Core.
The following file header is the used for .NET Core. Please use it for new files.
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.
- See class.cpp for an example of the header in a C++ file.
- See List.cs for an example of the header in a C# file.
.NET Core uses some files from other projects, typically where a binary distribution does not exist or would be inconvenient.
The following rules must be followed for PRs that include files from another project:
- The license of the file is permissive.
- The license of the file is left in-tact.
- The contribution is correctly attributed in the 3rd party notices file in the repository, as needed.
See IdnMapping.cs for an example of a file copied from another project and attributed in the CoreCLR 3rd party notices file.
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 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.
You must sign a .NET Foundation Contribution License Agreement (CLA) before your PR will be merged. This is a one-time requirement for projects in the .NET Foundation. You can read more about Contribution License Agreements (CLA) on Wikipedia.
The agreement: net-foundation-contribution-license-agreement.pdf
You don't have to do this up-front. You can simply clone, fork, and submit your pull-request as usual. When your pull-request is created, it is classified by a CLA bot. If the change is trivial (e.g. you just fixed a typo), then the PR is labelled with cla-not-required. Otherwise it's classified as cla-required. Once you signed a CLA, the current and all future pull-requests will be labelled as cla-signed.
Microsoft has issued a Patent Promise for .NET Libraries and Runtime Components.