1# Contributing to Protocol Buffers 2 3We welcome your contributions to protocol buffers. This doc describes the 4process to contribute patches to protobuf and the general guidelines we 5expect contributors to follow. 6 7## Before You Start 8 9We accept patches in the form of github pull requests. If you are new to 10github, please read [How to create github pull requests](https://help.github.com/articles/about-pull-requests/) 11first. 12 13### Contributor License Agreements 14 15Contributions to this project must be accompanied by a Contributor License 16Agreement. You (or your employer) retain the copyright to your contribution, 17this simply gives us permission to use and redistribute your contributions 18as part of the project. 19 20* If you are an individual writing original source code and you're sure you 21 own the intellectual property, then you'll need to sign an [individual CLA](https://cla.developers.google.com/about/google-individual?csw=1). 22* If you work for a company that wants to allow you to contribute your work, 23 then you'll need to sign a [corporate CLA](https://cla.developers.google.com/about/google-corporate?csw=1). 24 25### Coding Style 26 27This project follows [Google’s Coding Style Guides](https://github.com/google/styleguide). 28Before sending out your pull request, please familiarize yourself with the 29corresponding style guides and make sure the proposed code change is style 30conforming. 31 32## Contributing Process 33 34Most pull requests should go to the master branch and the change will be 35included in the next major/minor version release (e.g., 3.6.0 release). If you 36need to include a bug fix in a patch release (e.g., 3.5.2), make sure it’s 37already merged to master, and then create a pull request cherry-picking the 38commits from master branch to the release branch (e.g., branch 3.5.x). 39 40For each pull request, a protobuf team member will be assigned to review the 41pull request. For minor cleanups, the pull request may be merged right away 42after an initial review. For larger changes, you will likely receive multiple 43rounds of comments and it may take some time to complete. We will try to keep 44our response time within 7-days but if you don’t get any response in a few 45days, feel free to comment on the threads to get our attention. We also expect 46you to respond to our comments within a reasonable amount of time. If we don’t 47hear from you for 2 weeks or longer, we may close the pull request. You can 48still send the pull request again once you have time to work on it. 49 50Once a pull request is merged, we will take care of the rest and get it into 51the final release. 52 53## Pull Request Guidelines 54 55* If you are a Googler, it is preferable to first create an internal CL and 56 have it reviewed and submitted. The code propagation process will deliver the 57 change to GitHub. 58* Create small PRs that are narrowly focused on addressing a single concern. 59 We often receive PRs that are trying to fix several things at a time, but if 60 only one fix is considered acceptable, nothing gets merged and both author's 61 & review's time is wasted. Create more PRs to address different concerns and 62 everyone will be happy. 63* For speculative changes, consider opening an issue and discussing it first. 64 If you are suggesting a behavioral or API change, make sure you get explicit 65 support from a protobuf team member before sending us the pull request. 66* Provide a good PR description as a record of what change is being made and 67 why it was made. Link to a GitHub issue if it exists. 68* Don't fix code style and formatting unless you are already changing that 69 line to address an issue. PRs with irrelevant changes won't be merged. If 70 you do want to fix formatting or style, do that in a separate PR. 71* Unless your PR is trivial, you should expect there will be reviewer comments 72 that you'll need to address before merging. We expect you to be reasonably 73 responsive to those comments, otherwise the PR will be closed after 2-3 weeks 74 of inactivity. 75* Maintain clean commit history and use meaningful commit messages. PRs with 76 messy commit history are difficult to review and won't be merged. Use rebase 77 -i upstream/master to curate your commit history and/or to bring in latest 78 changes from master (but avoid rebasing in the middle of a code review). 79* Keep your PR up to date with upstream/master (if there are merge conflicts, 80 we can't really merge your change). 81* All tests need to be passing before your change can be merged. We recommend 82 you run tests locally before creating your PR to catch breakages early on. 83 Ultimately, the green signal will be provided by our testing infrastructure. 84 The reviewer will help you if there are test failures that seem not related 85 to the change you are making. 86 87## Reviewer Guidelines 88 89* Make sure that all tests are passing before approval. 90* Apply the "release notes: yes" label if the pull request's description should 91 be included in the next release (e.g., any new feature / bug fix). 92 Apply the "release notes: no" label if the pull request's description should 93 not be included in the next release (e.g., refactoring changes that does not 94 change behavior, integration from Google internal, updating tests, etc.). 95* Apply the appropriate language label (e.g., C++, Java, Python, etc.) to the 96 pull request. This will make it easier to identify which languages the pull 97 request affects, allowing us to better identify appropriate reviewer, create 98 a better release note, and make it easier to identify issues in the future. 99