diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f20057b..a86a938 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,20 +1,20 @@ -If you are interested in contributing to the gRPC project, below are some general guidelines that apply to all the repositories in gRPC Github organization. Please read the additional instructions in CONTRIBUTING.md file of the concerned repository. +If you are interested in contributing to the gRPC project, below are some general guidelines that apply to all the repositories in gRPC GitHub organization. Please read the additional instructions in CONTRIBUTING.md file of the concerned repository. ## Before You Contribute -We welcome and encourage contributions from the community. Please read the gRPC project [governance](https://github.com/grpc/grpc-community/blob/master/governance.md) document. Contributions should be made via pull requests. Pull requests will be reviewed by one or more maintainers and merged when acceptable. Please read the following guidelines carefully to maximize the chances of your PR being merged. +We welcome and encourage contributions from the community. Please read the gRPC project [governance](https://github.com/grpc/grpc-community/blob/main/governance.md) document. Contributions should be made via pull requests. Pull requests will be reviewed by one or more maintainers and merged when acceptable. Please read the following guidelines carefully to maximize the chances of your PR being merged. -For contributions not related to gRPC design and implementation but useful to gRPC community, please see gRPC [ecosystem guidelines](https://github.com/grpc/grpc-community/blob/master/grpc_ecosystem.md). +For contributions not related to gRPC design and implementation but useful to gRPC community, please see gRPC [ecosystem guidelines](https://github.com/grpc/grpc-community/blob/main/grpc_ecosystem.md). ## Legal Requirements In order to protect both you and the gRPC project, you will need to sign the CNCF [Contributor License Agreement](https://identity.linuxfoundation.org/projects/cncf) before your PR can be merged. ## Communication -Trivial changes and small bug fixes do not need prior communication. You can just submit a PR with minimum details. For larger PRs, we ask that before contributing, please make the effort to coordinate with the maintainers of the project via a Github issue or via [grpcio](https://groups.google.com/forum/#!forum/grpc-io) mailing list. This will prevent you from doing extra or redundant work that may or may not be merged. +Trivial changes and small bug fixes do not need prior communication. You can just submit a PR with minimum details. For larger PRs, we ask that before contributing, please make the effort to coordinate with the maintainers of the project via a GitHub issue or via [grpcio](https://groups.google.com/forum/#!forum/grpc-io) mailing list. This will prevent you from doing extra or redundant work that may or may not be merged. ## Have Questions? -It is best to ask questions on forums other than Github repos. Github repos are for filing issues and submitting PRs. You have a higher chance of getting help from the community if you ask your questions on [grpcio](https://groups.google.com/forum/#!forum/grpc-io) mailing list or [Stackoverflow](https://stackoverflow.com/). +It is best to ask questions on forums other than GitHub repos. GitHub repos are for filing issues and submitting PRs. You have a higher chance of getting help from the community if you ask your questions on [grpcio](https://groups.google.com/forum/#!forum/grpc-io) mailing list or [Stackoverflow](https://stackoverflow.com/). ## Guidelines For Pull Requests @@ -24,10 +24,10 @@ How to get your contributions merged smoothly and quickly. * 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 and why it was made. Link to a GitHub issue if it exists. * Don't fix code style and formatting unless you are already changing that line to address an issue. PRs with irrelevant changes won't be merged. If you do want to fix formatting or style, do that in a separate PR. -* Unless your PR is trivial, you should expect there will be reviewer comments that you'll need to address before merging. We expect you to be reasonably responsive to those comments, otherwise the PR will be closed after 2-3 weeks of inactivity. +* Unless your PR is trivial, you should expect there will be reviewer comments that you'll need to address before merging. We expect you to be reasonably responsive to those comments; otherwise, the PR will be closed after 2-3 weeks of inactivity. * If you have non-trivial contributions, please consider adding an entry to the AUTHORS.md file in the concerned repository listing the copyright holder for the contribution (yourself, if you are signing the individual CLA, or your company, for corporate CLAs) in the same PR as your contribution. This needs to be done only once for each company or individual. Please keep this file in alphabetical order. -* 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. +* Maintain clean commit history and use meaningful commit messages. PRs with messy commit history are difficult to review and won't be merged. Use `git rebase -i upstream/master` or `git rebase -i upstream/main` to curate your commit history and/or to bring in latest changes from `master`/`main` but avoid rebasing in the middle of a code review. +* Keep your PR up to date with `upstream/master`/`upstream/main`. If there are merge conflicts, we can't really merge your change. -Above are general guidelines that apply to all the repositories in gRPC Github organization. Please read the additional instructions in CONTRIBUTING.md file of the concerned repository. +Above are general guidelines that apply to all the repositories in gRPC GitHub organization. Please read the additional instructions in CONTRIBUTING.md file of the concerned repository. diff --git a/governance.md b/governance.md index bf2ea38..40fe4a2 100644 --- a/governance.md +++ b/governance.md @@ -11,7 +11,7 @@ The gRPC community adheres to the following principles: ## Code Of Conduct -The gRPC community abides by the CNCF [code of conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md). Here is an excerpt: +The gRPC community abides by the CNCF [code of conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md). Here is an excerpt: *As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.* @@ -19,7 +19,7 @@ The gRPC developers and community are expected to follow the values defined in t ## Decision Making And Voting -gRPC is an open-source [project](https://github.com/grpc/)(organization) with an open collaboration philosophy. This means that the Github project is the source of truth for every aspect of the project, including its philosophy, design, road map, and APIs. *If it's part of the project, it's in the repos. If it's in the repos, it's part of the project.* +gRPC is an open-source [project](https://github.com/grpc/)(organization) with an open collaboration philosophy. This means that the GitHub project is the source of truth for every aspect of the project, including its philosophy, design, road map, and APIs. *If it's part of the project, it's in the repos. If it's in the repos, it's part of the project.* As a result, all decisions can be expressed as changes to the repository. An implementation change is a change to the source code. An API change is a change to the API specification. A philosophy change is a change to the philosophy manifesto, and so on. @@ -29,7 +29,7 @@ All decisions affecting gRPC, big and small, follow the same 3 steps: * Step 2: Discuss the pull request. Anyone can do this. * Step 3: Maintainers merge or refuse the pull request. -In general, we prefer that technical issues and maintainer membership are amicably worked out between the persons involved. If a dispute cannot be decided independently, the maintainers can be called in to resolve the issue by voting. The same PR can be used or a separate PR can be opened in the concerned repository for voting. The title of a PR related to voting should be prefixed with “[vote]”. Such PRs should remain open for a minimum of two weeks unless a decision has been reached sooner. A formal voting on the PR is not required if majority of the maintainers have already agreed in other forums or meetings. In such cases, a detailed comment must be added by a maintainer before approving or rejecting the PR. In such a case, only an existing maintainer can ask for a formal vote to challenge the decision. Each maintainer can cast a maximum of one vote regardless of the number of repositories the maintainer is listed in. A simple majority is required to approve the PR. Only the maintainers listed in MAINTAINERS.md file of the concerned repository may vote on the PR. For cross-repository issues, the PR can be opened in [grpc-community](https://github.com/grpc/grpc-community) or [proposal](https://github.com/grpc/proposal) repositories. The list of maintainers in these repositories is a superset of the list of maintainers in all other repositories in the gRPC Github organization. For ease of maintenance only a few senior maintainers will have write access to grpc-community and proposal repositories. +In general, we prefer that technical issues and maintainer membership are amicably worked out between the persons involved. If a dispute cannot be decided independently, the maintainers can be called in to resolve the issue by voting. The same PR can be used or a separate PR can be opened in the concerned repository for voting. The title of a PR related to voting should be prefixed with “[vote]”. Such PRs should remain open for a minimum of two weeks unless a decision has been reached sooner. A formal voting on the PR is not required if majority of the maintainers have already agreed in other forums or meetings. In such cases, a detailed comment must be added by a maintainer before approving or rejecting the PR. In such a case, only an existing maintainer can ask for a formal vote to challenge the decision. Each maintainer can cast a maximum of one vote regardless of the number of repositories the maintainer is listed in. A simple majority is required to approve the PR. Only the maintainers listed in MAINTAINERS.md file of the concerned repository may vote on the PR. For cross-repository issues, the PR can be opened in [grpc-community](https://github.com/grpc/grpc-community) or [proposal](https://github.com/grpc/proposal) repositories. The list of maintainers in these repositories is a superset of the list of maintainers in all other repositories in the gRPC GitHub organization. For ease of maintenance only a few senior maintainers will have write access to grpc-community and proposal repositories. ## The gRFC Process @@ -37,7 +37,7 @@ We use [gRFCs](https://github.com/grpc/proposal/blob/master/README.md) for any s ## How To Contribute -See the general guidelines [here](https://github.com/grpc/grpc-community/blob/master/CONTRIBUTING.md) on how to contribute to gRPC project. If you want to become a maintainer see the section below. +See the [general guidelines](https://github.com/grpc/grpc-community/blob/main/CONTRIBUTING.md) on how to contribute to gRPC project. If you want to become a maintainer see the section below. ## How To Become A Maintainer @@ -47,7 +47,7 @@ Maintainers (also known as Committers) are first and foremost contributors that * Cast a vote on issues requiring voting. Contributors wanting to become maintainers are expected to: -* Be involved in contributing code, pull request review, triage of issues and addressing user questions in one or more forums such as [Github](https://github.com/grpc), [grpcio](https://groups.google.com/forum/#!forum/grpc-io) mailing list, [Stackoverflow](https://stackoverflow.com/search?q=grpc) and [Gitter](https://gitter.im/grpc/grpc). +* Be involved in contributing code, pull request review, triage of issues and addressing user questions in one or more forums such as [GitHub](https://github.com/grpc), [grpcio](https://groups.google.com/forum/#!forum/grpc-io) mailing list, [Stackoverflow](https://stackoverflow.com/search?q=grpc) and [Gitter](https://gitter.im/grpc/grpc). * Maintain sustained contribution to the gRPC project and spend a reasonable amount of time on it. * Show deep understanding of the areas contributed to, and good consideration of various reliability, usability, backward compatibility and performance requirements. @@ -55,7 +55,7 @@ These are a few ways to become a maintainer: * Create a PR adding yourself to MAINTAINERS.md in the appropriate repository. Before doing so it is a good practice to socialize with some existing maintainers to get a good feel for whether you meet the above criteria. A simple majority vote is required to approve the PR. See above for the voting process. * Current maintainers may nominate a contributor and confer maintainer status. A formal voting on the PR is not required if majority maintainers have already agreed in other forums or meetings. -Please note that in order to be part of the organization, your Github account needs to have [two factor security](https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/) enabled. +Please note that in order to be part of the organization, your GitHub account needs to have [two factor security](https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/) enabled. ## Losing Maintainer Status @@ -67,11 +67,11 @@ Similar to adding maintainers, new repositories can be added to gRPC GitHub orga ## Handling Security Vulnerabilities -The process for handling any security vulnerabilities or concerns found in gRPC is described [here](https://github.com/grpc/proposal/blob/master/P4-grpc-cve-process.md). This process is known as the gRPC CVE (Common Vulnerabilities and Exposure) process. +There is a process for handling any security vulnerabilities or concerns found in gRPC. This process is known as the [gRPC CVE (Common Vulnerabilities and Exposure) process](https://github.com/grpc/proposal/blob/master/P4-grpc-cve-process.md). ## Releases -Details on gRPC release process and schedule can be found [here](https://github.com/grpc/grpc/blob/master/doc/grpc_release_schedule.md). Each repository has its own release process. We are in the process of making the release instructions publicly available. Only maintainers can do the releases. +See the [gRPC release process and schedule](https://github.com/grpc/grpc/blob/master/doc/grpc_release_schedule.md). Each repository has its own release process. We are in the process of making the release instructions publicly available. Only maintainers can do the releases. ## Changes In Governance