|
| 1 | +# Contributing Guide |
| 2 | + |
| 3 | +> :warning: Please note, this document is a subset of [Contributing to .NET Runtime][net-contributing], make sure to read it first. |
| 4 | +
|
| 5 | +* [Reporting Issues](#reporting-issues) |
| 6 | + + [Identify Where to Report](#identify-where-to-report) |
| 7 | + + [Finding Existing Issues](#finding-existing-issues) |
| 8 | + + [Writing a Good API Proposal](#writing-a-good-api-proposal) |
| 9 | + + [Writing a Good Bug Report](#writing-a-good-bug-report) |
| 10 | + - [Why are Minimal Reproductions Important?](#why-are-minimal-reproductions-important) |
| 11 | + - [Are Minimal Reproductions Required?](#are-minimal-reproductions-required) |
| 12 | + - [How to Create a Minimal Reproduction](#how-to-create-a-minimal-reproduction) |
| 13 | +* [Contributing Changes](#contributing-changes) |
| 14 | + + [DOs and DON'Ts](#dos-and-donts) |
| 15 | + + [Breaking Changes](#breaking-changes) |
| 16 | + + [Suggested Workflow](#suggested-workflow) |
| 17 | + + [Commit Messages](#commit-messages) |
| 18 | + + [PR Feedback](#pr-feedback) |
| 19 | + + [Help Wanted (Up for Grabs)](#help-wanted-up-for-grabs) |
| 20 | + + [Contributor License Agreement](#contributor-license-agreement) |
| 21 | + |
| 22 | +You can contribute with issues, pull-requests, and general reviews of both issues and pull-requests. Simply filing issues for problems you encounter is a great way to contribute. Contributing implementations is greatly appreciated. |
| 23 | + |
| 24 | +## Reporting Issues |
| 25 | + |
| 26 | +We always welcome bug reports, API proposals and overall feedback. Here are a few tips on how you can make reporting your issue as effective as possible. |
| 27 | + |
| 28 | +### Identify Where to Report |
| 29 | + |
| 30 | +The .NET codebase is distributed across multiple repositories in the [.NET organization](https://github.com/dotnet). Depending on the feedback you might want to file the issue on a different repo. Here are a few common repos: |
| 31 | + |
| 32 | +* [dotnet/extensions](https://github.com/dotnet/extensions) out-of-box .NET Platform Extensions. |
| 33 | +* [dotnet/runtime](https://github.com/dotnet/runtime) .NET runtime, libraries and shared host installers. |
| 34 | +* [dotnet/aspnetcore](https://github.com/dotnet/aspnetcore) ASP.NET Core. |
| 35 | + |
| 36 | +### Finding Existing Issues |
| 37 | + |
| 38 | +Before filing a new issue, please search our [open issues](https://github.com/dotnet/extensions-samples/issues) to check if it already exists. |
| 39 | + |
| 40 | +If you do find an existing issue, please include your own feedback in the discussion. Do consider upvoting (👍 reaction) the original post, as this helps us prioritize popular issues in our backlog. |
| 41 | + |
| 42 | +### Writing a Good Bug Report |
| 43 | + |
| 44 | +Good bug reports make it easier for maintainers to verify and root cause the underlying problem. The better a bug report, the faster the problem will be resolved. Ideally, a bug report should contain the following information: |
| 45 | + |
| 46 | +* A high-level description of the problem. |
| 47 | +* A _minimal reproduction_, i.e. the smallest size of code/configuration required to reproduce the wrong behavior. |
| 48 | +* A description of the _expected behavior_, contrasted with the _actual behavior_ observed. |
| 49 | +* Information on the environment: OS/distro, CPU arch, SDK version, etc. |
| 50 | +* Additional information, e.g. is it a regression from previous versions? are there any known workarounds? |
| 51 | + |
| 52 | +When ready to submit a bug report, please use the [Bug Report issue template](https://github.com/dotnet/extensions/issues/new?assignees=&labels=&template=01_bug_report.yml). |
| 53 | + |
| 54 | +#### Why are Minimal Reproductions Important? |
| 55 | + |
| 56 | +A reproduction lets maintainers verify the presence of a bug, and diagnose the issue using a debugger. A _minimal_ reproduction is the smallest possible console application demonstrating that bug. Minimal reproductions are generally preferable since they: |
| 57 | + |
| 58 | +1. Focus debugging efforts on a simple code snippet, |
| 59 | +2. Ensure that the problem is not caused by unrelated dependencies/configuration, |
| 60 | +3. Avoid the need to share production codebases. |
| 61 | + |
| 62 | +#### Are Minimal Reproductions Required? |
| 63 | + |
| 64 | +In certain cases, creating a minimal reproduction might not be practical (e.g. due to nondeterministic factors, external dependencies). In such cases you would be asked to provide as much information as possible, for example by sharing a memory dump of the failing application. If maintainers are unable to root cause the problem, they might still close the issue as not actionable. While not required, minimal reproductions are strongly encouraged and will significantly improve the chances of your issue being prioritized and fixed by the maintainers. |
| 65 | + |
| 66 | +#### How to Create a Minimal Reproduction |
| 67 | + |
| 68 | +The best way to create a minimal reproduction is gradually removing code and dependencies from a reproducing app, until the problem no longer occurs. A good minimal reproduction: |
| 69 | + |
| 70 | +* Excludes all unnecessary types, methods, code blocks, source files, nuget dependencies and project configurations. |
| 71 | +* Contains documentation or code comments illustrating expected vs actual behavior. |
| 72 | +* If possible, avoids performing any unneeded IO or system calls. For example, can the ASP.NET based reproduction be converted to a plain old console app? |
| 73 | + |
| 74 | +## Contributing Changes |
| 75 | + |
| 76 | +Project maintainers will merge changes that improve the product significantly. |
| 77 | + |
| 78 | +The [Pull Request Guide][pr-guide] and [Copyright][copyright-guide] docs define additional guidance. |
| 79 | + |
| 80 | +### DOs and DON'Ts |
| 81 | + |
| 82 | +Please do: |
| 83 | + |
| 84 | +* **DO** follow our [coding style][coding-style] (C# code-specific)<br/> |
| 85 | + We strive to wrap the lines around 120 mark, and it's acceptable to stretch to no more than 150 chars (with some exceptions being URLs). [EditorGuidelines VS extension](https://marketplace.visualstudio.com/items?itemName=PaulHarrington.EditorGuidelines) makes it easier to visualise (see https://github.com/dotnet/winforms/pull/4836). |
| 86 | +* **DO** give priority to the current style of the project or file you're changing even if it diverges from the general guidelines. |
| 87 | +* **DO** include tests when adding new features. When fixing bugs, start with |
| 88 | + adding a test that highlights how the current behavior is broken. |
| 89 | +* **DO** keep the discussions focused. When a new or related topic comes up |
| 90 | + it's often better to create new issue than to side track the discussion. |
| 91 | +* **DO** blog and tweet (or whatever) about your contributions, frequently! |
| 92 | + |
| 93 | +Please do not: |
| 94 | + |
| 95 | +* **DON'T** make PRs for style changes. |
| 96 | +* **DON'T** surprise us with big pull requests. Instead, file an issue and start |
| 97 | + a discussion so we can agree on a direction before you invest a large amount |
| 98 | + of time. |
| 99 | +* **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. |
| 100 | +* **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. |
| 101 | +* **DON'T** add API additions without filing an issue and discussing with us first. See [API Review Process][api-review-process]. |
| 102 | + |
| 103 | +### Commit Messages |
| 104 | + |
| 105 | +Please format commit messages as follows (based on [A Note About Git Commit Messages][note-about-git-commit-messages]). Also, use the [GitHub keywords][github-keywords]: |
| 106 | + |
| 107 | + ``` |
| 108 | + Summarize change in 50 characters or less |
| 109 | + |
| 110 | + Fixes #42 |
| 111 | + |
| 112 | + Provide more detail after the first line. Leave one blank line below the |
| 113 | + summary and wrap all lines at 72 characters or less. |
| 114 | + |
| 115 | + If the change fixes an issue, leave another blank line after the final |
| 116 | + paragraph and indicate which issue is fixed in the specific format |
| 117 | + below. |
| 118 | + ``` |
| 119 | + |
| 120 | +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. |
| 121 | + |
| 122 | +### PR Feedback |
| 123 | + |
| 124 | +Project maintainers 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. |
| 125 | + |
| 126 | +One or more project maintainers 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". |
| 127 | + |
| 128 | +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. |
| 129 | + |
| 130 | +### Help Wanted (Up for Grabs) |
| 131 | + |
| 132 | +The team marks the most straightforward issues as [help wanted](https://github.com/dotnet/extensions/labels/help%20wanted). This set of issues is the place to start if you are interested in contributing but new to the codebase. |
| 133 | + |
| 134 | +### Contributor License Agreement |
| 135 | + |
| 136 | +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. |
| 137 | + |
| 138 | +The agreement: [net-foundation-contribution-license-agreement.pdf](https://github.com/dotnet/home/blob/master/guidance/net-foundation-contribution-license-agreement.pdf) |
| 139 | + |
| 140 | +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`. |
| 141 | + |
| 142 | + |
| 143 | +[comment]: <> (URI Links) |
| 144 | + |
| 145 | +[api-review-process]: https://github.com/dotnet/runtime/blob/main/docs/project/api-review-process.md |
| 146 | +[breaking-changes]: https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/breaking-changes.md |
| 147 | +[breaking-changes-public-contract]: https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/breaking-changes.md#bucket-1-public-contract |
| 148 | +[coding-style]: https://github.com/dotnet/runtime/blob/master/docs/coding-guidelines/coding-style.md |
| 149 | +[copyright-guide]: https://github.com/dotnet/runtime/blob/main/docs/project/copyright.md |
| 150 | +[github-keywords]: https://docs.github.com/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests#linking-a-pull-request-to-an-issue |
| 151 | +[net-contributing]: https://github.com/dotnet/extensions/blob/main/CONTRIBUTING.md |
| 152 | +[note-about-git-commit-messages]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html |
| 153 | +[pr-guide]: https://github.com/dotnet/runtime/blob/main/docs/pr-guide.md |
0 commit comments