grpc
/
grpc-go
mirror of https://github.com/grpc/grpc-go.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update CONTRIBUTING.md (#8300)

This commit is contained in:
Doug Fawley 2025-05-09 09:57:52 -07:00 committed by GitHub
parent 950a7cfdfd
commit d46d6d8962
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 81 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

131
CONTRIBUTING.md
View File

@ -1,73 +1,102 @@
# How to contribute # How to contribute
We definitely welcome your patches and contributions to gRPC! Please read the gRPC We welcome your patches and contributions to gRPC! Please read the gRPC
organization's [governance rules](https://github.com/grpc/grpc-community/blob/master/governance.md) organization's [governance
and [contribution guidelines](https://github.com/grpc/grpc-community/blob/master/CONTRIBUTING.md) before proceeding. rules](https://github.com/grpc/grpc-community/blob/master/governance.md) before
proceeding.
If you are new to GitHub, please start by reading [Pull Request howto](https://help.github.com/articles/about-pull-requests/) If you are new to GitHub, please start by reading [Pull Request howto](https://help.github.com/articles/about-pull-requests/)
## Legal requirements ## Legal requirements
In order to protect both you and ourselves, you will need to sign the In order to protect both you and ourselves, you will need to sign the
[Contributor License Agreement](https://identity.linuxfoundation.org/projects/cncf). [Contributor License
Agreement](https://identity.linuxfoundation.org/projects/cncf). When you create
your first PR, a link will be added as a comment that contains the steps needed
to complete this process.
## Getting Started
A great way to start is by searching through our open issues. [Unassigned issues
labeled as "help
wanted"](https://github.com/grpc/grpc-go/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20label%3A%22Status%3A%20Help%20Wanted%22%20no%3Aassignee)
are especially nice for first-time contributors, as they should be well-defined
problems that already have agreed-upon solutions.
## Code Style
We follow [Google's published Go style
guide](https://google.github.io/styleguide/go/). Note that there are three
primary documents that make up this style guide; please follow them as closely
as possible. If a reviewer recommends something that contradicts those
guidelines, there may be valid reasons to do so, but it should be rare.
## Guidelines for Pull Requests ## Guidelines for Pull Requests
How to get your contributions merged smoothly and quickly.
How to get your contributions merged smoothly and quickly:
- Create **small PRs** that are narrowly focused on **addressing a single - Create **small PRs** that are narrowly focused on **addressing a single
concern**. We often times receive PRs that are trying to fix several things at concern**. We often receive PRs that attempt to fix several things at the same
a time, but only one fix is considered acceptable, nothing gets merged and time, and if one part of the PR has a problem, that will hold up the entire
both author's & review's time is wasted. Create more PRs to address different PR.
concerns and everyone will be happy.
- If you are searching for features to work on, issues labeled [Status: Help - For **speculative changes**, consider opening an issue and discussing it
Wanted](https://github.com/grpc/grpc-go/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22Status%3A+Help+Wanted%22) first. If you are suggesting a behavioral or API change, consider starting
is a great place to start. These issues are well-documented and usually can be with a [gRFC proposal](https://github.com/grpc/proposal). Many new features
resolved with a single pull request. that are not bug fixes will require cross-language agreement.
- If you are adding a new file, make sure it has the copyright message template - If you want to fix **formatting or style**, consider whether your changes are
at the top as a comment. You can copy over the message from an existing file an obvious improvement or might be considered a personal preference. If a
and update the year. style change is based on preference, it likely will not be accepted. If it
corrects widely agreed-upon anti-patterns, then please do create a PR and
explain the benefits of the change.
- The grpc package should only depend on standard Go packages and a small number - For correcting **misspellings**, please be aware that we use some terms that
of exceptions. If your contribution introduces new dependencies which are NOT are sometimes flagged by spell checkers. As an example, "if an only if" is
in the [list](https://godoc.org/google.golang.org/grpc?imports), you need a often written as "iff". Please do not make spelling correction changes unless
discussion with gRPC-Go authors and consultants. you are certain they are misspellings.
- For speculative changes, consider opening an issue and discussing it first. If
you are suggesting a behavioral or API change, consider starting with a [gRFC
proposal](https://github.com/grpc/proposal).
- Provide a good **PR description** as a record of **what** change is being made - Provide a good **PR description** as a record of **what** change is being made
and **why** it was made. Link to a GitHub issue if it exists. and **why** it was made. Link to a GitHub issue if it exists.
- If you want to fix formatting or style, consider whether your changes are an - Maintain a **clean commit history** and use **meaningful commit messages**.
obvious improvement or might be considered a personal preference. If a style PRs with messy commit histories are difficult to review and won't be merged.
change is based on preference, it likely will not be accepted. If it corrects Before sending your PR, ensure your changes are based on top of the latest
widely agreed-upon anti-patterns, then please do create a PR and explain the `upstream/master` commits, and avoid rebasing in the middle of a code review.
benefits of the change. You should **never use `git push -f`** unless absolutely necessary during a
review, as it can interfere with GitHub's tracking of comments.
- Unless your PR is trivial, you should expect there will be reviewer comments
that you'll need to address before merging. We'll mark it as `Status: Requires
Reporter Clarification` if we expect you to respond to these comments in a
timely manner. If the PR remains inactive for 6 days, it will be marked as
`stale` and automatically close 7 days after that if we don't hear back from
you.
- Maintain **clean commit history** and use **meaningful commit messages**. PRs
with messy commit history are difficult to review and won't be merged. Use
`rebase -i upstream/master` to curate your commit history and/or to bring in
latest changes from master (but avoid rebasing in the middle of a code
review).
- Keep your PR up to date with upstream/master (if there are merge conflicts, we
can't really merge your change).
- **All tests need to be passing** before your change can be merged. We - **All tests need to be passing** before your change can be merged. We
recommend you **run tests locally** before creating your PR to catch breakages recommend you run tests locally before creating your PR to catch breakages
early on. early on:
- `./scripts/vet.sh` to catch vet errors
- `go test -cpu 1,4 -timeout 7m ./...` to run the tests
- `go test -race -cpu 1,4 -timeout 7m ./...` to run tests in race mode
- Exceptions to the rules can be made if there's a compelling reason for doing so. - `./scripts/vet.sh` to catch vet errors.
- `go test -cpu 1,4 -timeout 7m ./...` to run the tests.
- `go test -race -cpu 1,4 -timeout 7m ./...` to run tests in race mode.
Note that we have a multi-module repo, so `go test` commands may need to be
run from the root of each module in order to cause all tests to run.
*Alternatively*, you may find it easier to push your changes to your fork on
GitHub, which will trigger a GitHub Actions run that you can use to verify
everything is passing.
- If you are adding a new file, make sure it has the **copyright message**
template at the top as a comment. You can copy the message from an existing
file and update the year.
- The grpc package should only depend on standard Go packages and a small number
of exceptions. **If your contribution introduces new dependencies**, you will
need a discussion with gRPC-Go maintainers. A github action check will run on
every PR, and will flag any transitive dependency changes from any public
package.
- Unless your PR is trivial, you should **expect reviewer comments** that you
will need to address before merging. We'll label the PR as `Status: Requires
Reporter Clarification` if we expect you to respond to these comments in a
timely manner. If the PR remains inactive for 6 days, it will be marked as
`stale`, and we will automatically close it after 7 days if we don't hear back
from you. Please feel free to ping issues or bugs if you do not get a response
within a week.
- Exceptions to the rules can be made if there's a compelling reason to do so.

1
README.md
View File

@ -32,6 +32,7 @@ import "google.golang.org/grpc"
- [Low-level technical docs](Documentation) from this repository - [Low-level technical docs](Documentation) from this repository
- [Performance benchmark][] - [Performance benchmark][]
- [Examples](examples) - [Examples](examples)
- [Contribution guidelines](CONTRIBUTING.md)
## FAQ ## FAQ