document the kinds of patches the repo is open to (#8900)
* document the kinds of patches the repo is open to
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index db1ff31..8ef5dd2 100644
--- a/CONTRIBUTING.md
+++ b/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 @@
* 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
