document the kinds of patches the repo is open to (#8900)

* document the kinds of patches the repo is open to
pull/9096/head
Elliotte Rusty Harold 3 years ago committed by GitHub
parent 5c8018c378
commit ab993cf6ca
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
  1. 26
      CONTRIBUTING.md

@ -1,9 +1,31 @@
# Contributing to Protocol Buffers
We welcome your contributions to protocol buffers. This doc describes the
We welcome some types of contributions to protocol buffers. This doc describes the
process to contribute patches to protobuf and the general guidelines we
expect contributors to follow.
## What We Accept
* Bug fixes with unit tests demonstrating the problem are very welcome.
We also appreciate bug reports, even when they don't come with a patch.
Bug fixes without tests are usually not accepted.
* New APIs and features with adequate test coverage and documentation
may be accepted if they do not compromise backwards
compatibility. However there's a fairly high bar of usefulness a new public
method must clear before it will be accepted. Features that are fine in
isolation are often rejected because they don't have enough impact to justify the
conceptual burden and ongoing maintenance cost. It's best to file an issue
and get agreement from maintainers on the value of a new feature before
working on a PR.
* Performance optimizations may be accepted if they have convincing benchmarks that demonstrate
an improvement and they do not significantly increase complexity.
* Changes to existing APIs are almost never accepted. Stability and
backwards compatibility are paramount. In the unlikely event a breaking change
is required, it must usually be implemented in google3 first.
* Changes to the wire and text formats are never accepted. Any breaking change
to these formats would have to be implemented as a completely new format.
We cannot begin generating protos that cannot be parsed by existing code.
## Before You Start
We accept patches in the form of github pull requests. If you are new to
@ -58,7 +80,7 @@ the final release.
* Create small PRs that are narrowly focused on addressing a single concern.
We often receive PRs that are trying to fix several things at a time, but if
only one fix is considered acceptable, nothing gets merged and both author's
& review's time is wasted. Create more PRs to address different concerns and
& reviewer's time is wasted. Create more PRs to address different concerns and
everyone will be happy.
* For speculative changes, consider opening an issue and discussing it first.
If you are suggesting a behavioral or API change, make sure you get explicit

Loading…
Cancel
Save