CONTRIBUTING.md

   1 Contribution to .NET Runtime
   2 =====================
   3
   4 You can contribute to .NET Runtime with issues and PRs. Simply filing issues for problems you encounter is a great way to contribute. Contributing implementations is greatly appreciated.
   5
   6 ## Contribution "Bar"
   7
   8 Project maintainers will merge changes that improve the product significantly and broadly and that align with the [.NET Core roadmap](https://github.com/dotnet/core/blob/master/roadmap.md).
   9
  10 Maintainers will not merge changes that have narrowly-defined benefits, due to compatibility risk. The .NET Core codebase is used by several Microsoft products (for example, ASP.NET Core, .NET Framework 4.x, Windows Universal Apps) to enable execution of managed code. Other companies are building products on top of .NET, too. We may revert changes if they are found to be breaking.
  11
  12 Contributions must also satisfy the other published guidelines defined in this document.
  13
  14 ## DOs and DON'Ts
  15
  16 Please do:
  17
  18 * **DO** follow our [coding style](docs/coding-guidelines/coding-style.md) (C# code-specific)
  19 * **DO** give priority to the current style of the project or file you're changing even if it diverges from the general guidelines.
  20 * **DO** include tests when adding new features. When fixing bugs, start with
  21   adding a test that highlights how the current behavior is broken.
  22 * **DO** keep the discussions focused. When a new or related topic comes up
  23   it's often better to create new issue than to side track the discussion.
  24 * **DO** blog and tweet (or whatever) about your contributions, frequently!
  25
  26 Please do not:
  27
  28 * **DON'T** make PRs for style changes.
  29 * **DON'T** surprise us with big pull requests. Instead, file an issue and start
  30   a discussion so we can agree on a direction before you invest a large amount
  31   of time.
  32 * **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.
  33 * **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.
  34 * **DON'T** add API additions without filing an issue and discussing with us first. See [API Review Process](docs/project/api-review-process.md).
  35
  36 ## Managed Code Compatibility
  37
  38 Contributions must maintain [API signature](docs/coding-guidelines/breaking-changes.md#bucket-1-public-contract) and behavioral compatibility. Contributions that include [breaking changes](docs/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.
  39
  40 ## Suggested Workflow
  41
  42 We use and recommend the following workflow:
  43
  44 1. Create an issue for your work.
  45     - You can skip this step for trivial changes.
  46     - Reuse an existing issue on the topic, if there is one.
  47     - Get agreement from the team and the community that your proposed change is a good one.
  48     - If your change adds a new API, follow the [API Review Process](docs/project/api-review-process.md).
  49     - Clearly state that you are going to take on implementing it, if that's the case. You can request that the issue be assigned to you. Note: The issue filer and the implementer don't have to be the same person.
  50 2. Create a personal fork of the repository on GitHub (if you don't already have one).
  51 3. In your fork, create a branch off of master (`git checkout -b mybranch`).
  52     - Name the branch so that it clearly communicates your intentions, such as issue-123 or githubhandle-issue.
  53     - Branches are useful since they isolate your changes from incoming changes from upstream. They also enable you to create multiple PRs from the same fork.
  54 4. Make and commit your changes to your branch.
  55     - Please follow our [Commit Messages](#commit-messages) guidance.
  56 5. Add new tests corresponding to your change, if applicable.
  57 6. Build the repository with your changes.
  58     - Make sure that the builds are clean.
  59     - Make sure that the tests are all passing, including your new tests.
  60 7. Create a pull request (PR) against the dotnet/runtime repository's **master** branch.
  61     - State in the description what issue or improvement your change is addressing.
  62     - Check if all the Continuous Integration checks are passing.
  63 8. Wait for feedback or approval of your changes from the [area owners](docs/area-owners.md).
  64     - Details about the pull request [review procedure](docs/pr-guide.md).
  65 9. When area owners have signed off, and all checks are green, your PR will be merged.
  66     - The next official build will automatically include your change.
  67     - You can delete the branch you used for making the change.
  68
  69 Note: It is OK for your PR to include a large number of commits. Once your change is accepted, you will be asked to squash your commits into one or some appropriately small number of commits before your PR is merged.
  70
  71 Note: It is OK to create your PR as "[WIP]" on the upstream repo before the implementation is done. This can be useful if you'd like to start the feedback process concurrent with your implementation. State that this is the case in the initial PR comment.
  72
  73 ## Up for Grabs
  74
  75 The team marks the most straightforward issues as [up for grabs](https://github.com/dotnet/runtime/labels/up-for-grabs). This set of issues is the place to start if you are interested in contributing but new to the codebase.
  76
  77 Some issues have not yet been migrated here from our "old" repos. You can find those here:
  78
  79 [CoreFX up for grabs](https://github.com/dotnet/corefx/issues?q=is%3Aopen+is%3Aissue+label%3Aup-for-grabs)
  80
  81 [CoreCLR up for grabs](https://github.com/dotnet/coreclr/issues?q=is%3Aopen+is%3Aissue+label%3Aup-for-grabs)
  82
  83 Even for these issues, the pull request should go to this repo.
  84
  85 ## Commit Messages
  86
  87 Please format commit messages as follows (based on [A Note About Git Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)):
  88
  89 ```
  90 Summarize change in 50 characters or less
  91
  92 Provide more detail after the first line. Leave one blank line below the
  93 summary and wrap all lines at 72 characters or less.
  94
  95 If the change fixes an issue, leave another blank line after the final
  96 paragraph and indicate which issue is fixed in the specific format
  97 below.
  98
  99 Fix #42
 100 ```
 101
 102 Also do your best to factor commits appropriately, 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.
 103
 104 ## Contributor License Agreement
 105
 106 You must sign a [.NET Foundation Contribution License Agreement (CLA)](https://cla.dotnetfoundation.org) 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)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) on Wikipedia.
 107
 108 The agreement: [net-foundation-contribution-license-agreement.pdf](https://github.com/dotnet/home/blob/master/guidance/net-foundation-contribution-license-agreement.pdf)
 109
 110 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 (for example, 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`.
 111
 112 ## File Headers
 113
 114 The following file header is the used for .NET Core. Please use it for new files.
 115
 116 ```
 117 // Licensed to the .NET Foundation under one or more agreements.
 118 // The .NET Foundation licenses this file to you under the MIT license.
 119 // See the LICENSE file in the project root for more information.
 120 ```
 121
 122 - See [class.cpp](./src/coreclr/src/vm/class.cpp) for an example of the header in a C++ file.
 123 - See [List.cs](./src/libraries/System.Private.CoreLib/src/System/Collections/Generic/List.cs) for an example of the header in a C# file.
 124
 125 ## PR - CI Process
 126
 127 The [dotnet continuous integration](https://dev.azure.com/dnceng/public/) (CI) system will automatically perform the required builds and run tests (including the ones you are expected to run) for PRs. Builds and test runs must be clean.
 128
 129 If the CI build fails for any reason, the PR issue will be updated with a link that can be used to determine the cause of the failure.
 130
 131 ## PR Feedback
 132
 133 Microsoft team and community members will provide feedback on your change. Community feedback is highly valued. You will often see the absence of team feedback if the community has already provided good review feedback.
 134
 135 One or more Microsoft team members will review every PR prior to merge. They will often reply with "LGTM, modulo comments". That means that the PR will be merged once the feedback is resolved. "LGTM" == "looks good to me".
 136
 137 There are lots of thoughts and [approaches](https://github.com/antlr/antlr4-cpp/blob/master/CONTRIBUTING.md#emoji) for how to efficiently discuss changes. It is best to be clear and explicit with your feedback. Please be patient with people who might not understand the finer details about your approach to feedback.
 138
 139 ## Contributing Ports
 140
 141 We encourage ports of CoreCLR to other platforms. There are multiple ports ongoing at any one time. You may be interested in one of the following ports:
 142
 143 Chips:
 144
 145 - [ARM32](https://github.com/dotnet/runtime/labels/arch-arm32)
 146 - [ARM64](https://github.com/dotnet/runtime/labels/arch-arm64)
 147 - [X86](https://github.com/dotnet/runtime/labels/arch-x86)
 148
 149 Operating System:
 150
 151 - [Linux](https://github.com/dotnet/runtime/labels/os-linux)
 152 - [macOS](https://github.com/dotnet/runtime/labels/os-mac-os-x)
 153 - [Windows Subsystem for Linux](https://github.com/dotnet/runtime/labels/os-windows-wsl)
 154 - [FreeBSD](https://github.com/dotnet/runtime/labels/os-freebsd)
 155
 156 Note: Add links to install instructions for each of these ports.
 157
 158 Ports have a weaker contribution bar, at least initially. A functionally correct implementation is considered an important first goal. Performance, reliability and compatibility are all important concerns after that.
 159
 160 ### Copying Files from Other Projects
 161
 162 .NET Core uses some files from other projects, typically where a binary distribution does not exist or would be inconvenient.
 163
 164 The following rules must be followed for PRs that include files from another project:
 165
 166 - The license of the file is [permissive](https://en.wikipedia.org/wiki/Permissive_free_software_licence).
 167 - The license of the file is left in-tact.
 168 - The contribution is correctly attributed in the [3rd party notices](./THIRD-PARTY-NOTICES.TXT) file in the repository, as needed.
 169
 170 See [IdnMapping.cs](./src/libraries/System.Private.CoreLib/src/System/Globalization/IdnMapping.cs) for an example of a file copied from another project and attributed in the [CoreCLR 3rd party notices](./THIRD-PARTY-NOTICES.TXT) file.
 171
 172 ### Porting Files from Other Projects
 173
 174 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.
 175
 176 [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.