CONTRIBUTING.md (3849B)
1 # How to contribute 2 3 We definitely welcome your patches and contributions to gRPC! Please read the gRPC 4 organization's [governance rules](https://github.com/grpc/grpc-community/blob/master/governance.md) 5 and [contribution guidelines](https://github.com/grpc/grpc-community/blob/master/CONTRIBUTING.md) before proceeding. 6 7 If you are new to github, please start by reading [Pull Request howto](https://help.github.com/articles/about-pull-requests/) 8 9 ## Legal requirements 10 11 In order to protect both you and ourselves, you will need to sign the 12 [Contributor License Agreement](https://identity.linuxfoundation.org/projects/cncf). 13 14 ## Guidelines for Pull Requests 15 How to get your contributions merged smoothly and quickly. 16 17 - Create **small PRs** that are narrowly focused on **addressing a single 18 concern**. We often times receive PRs that are trying to fix several things at 19 a time, but only one fix is considered acceptable, nothing gets merged and 20 both author's & review's time is wasted. Create more PRs to address different 21 concerns and everyone will be happy. 22 23 - If you are searching for features to work on, issues labeled [Status: Help 24 Wanted](https://github.com/grpc/grpc-go/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22Status%3A+Help+Wanted%22) 25 is a great place to start. These issues are well-documented and usually can be 26 resolved with a single pull request. 27 28 - If you are adding a new file, make sure it has the copyright message template 29 at the top as a comment. You can copy over the message from an existing file 30 and update the year. 31 32 - The grpc package should only depend on standard Go packages and a small number 33 of exceptions. If your contribution introduces new dependencies which are NOT 34 in the [list](https://godoc.org/google.golang.org/grpc?imports), you need a 35 discussion with gRPC-Go authors and consultants. 36 37 - For speculative changes, consider opening an issue and discussing it first. If 38 you are suggesting a behavioral or API change, consider starting with a [gRFC 39 proposal](https://github.com/grpc/proposal). 40 41 - Provide a good **PR description** as a record of **what** change is being made 42 and **why** it was made. Link to a github issue if it exists. 43 44 - If you want to fix formatting or style, consider whether your changes are an 45 obvious improvement or might be considered a personal preference. If a style 46 change is based on preference, it likely will not be accepted. If it corrects 47 widely agreed-upon anti-patterns, then please do create a PR and explain the 48 benefits of the change. 49 50 - Unless your PR is trivial, you should expect there will be reviewer comments 51 that you'll need to address before merging. We'll mark it as `Status: Requires 52 Reporter Clarification` if we expect you to respond to these comments in a 53 timely manner. If the PR remains inactive for 6 days, it will be marked as 54 `stale` and automatically close 7 days after that if we don't hear back from 55 you. 56 57 - Maintain **clean commit history** and use **meaningful commit messages**. PRs 58 with messy commit history are difficult to review and won't be merged. Use 59 `rebase -i upstream/master` to curate your commit history and/or to bring in 60 latest changes from master (but avoid rebasing in the middle of a code 61 review). 62 63 - Keep your PR up to date with upstream/master (if there are merge conflicts, we 64 can't really merge your change). 65 66 - **All tests need to be passing** before your change can be merged. We 67 recommend you **run tests locally** before creating your PR to catch breakages 68 early on. 69 - `VET_SKIP_PROTO=1 ./vet.sh` to catch vet errors 70 - `go test -cpu 1,4 -timeout 7m ./...` to run the tests 71 - `go test -race -cpu 1,4 -timeout 7m ./...` to run tests in race mode 72 73 - Exceptions to the rules can be made if there's a compelling reason for doing so.