1How to contribute 2================= 3 4Thank you so much for wanting to contribute to Guava! Here are a few important 5things you should know about contributing: 6 7 1. API changes require discussion, use cases, etc. Code comes later. 8 2. Pull requests are great for small fixes for bugs, documentation, etc. 9 3. Pull requests are not merged directly into the master branch. 10 3. Code contributions require signing a Google CLA. 11 12API changes 13----------- 14 15We make changes to Guava's public [APIs][], including adding new APIs, very 16carefully. Because of this, if you're interested in seeing a new feature in 17Guava, the best approach is to create an [issue][] (or comment on an existing 18issue if there is one) requesting the feature and describing specific use cases 19for it. 20 21If the feature has merit, it will go through a thorough process of API design 22and review. Any code should come after this. 23 24[APIs]: http://en.wikipedia.org/wiki/Application_programming_interface 25[issue]: https://github.com/google/guava/issues 26 27Pull requests 28------------- 29 30Unless the change is a trivial fix such as for a typo, it's generally best to 31start by opening a new issue describing the bug or feature you're intending to 32fix. Even if you think it's relatively minor, it's helpful to know what people 33are working on. And as mentioned above, API changes should be discussed 34thoroughly before moving to code. 35 36Some examples of types of pull requests that are immediately helpful: 37 38 - Fixing a bug without changing a public API. 39 - Fixing or improving documentation. 40 - Improvements to Maven configuration. 41 42Guidelines for any code contributions: 43 44 1. Any significant changes should be accompanied by tests. The project already 45 has good test coverage, so look at some existing tests if you're unsure 46 how to go about it. 47 2. All contributions must be licensed Apache 2.0 and all files must have a 48 copy of the boilerplate license comment (can be copied from an existing 49 file). 50 3. Files should be formatted according to Google's [Java style guide][]. 51 4. Please squash all commits for a change into a single commit (this can be 52 done using `git rebase -i`). Do your best to have a 53 [well-formed commit message][] for the change. 54 55[Java style guide]: https://google.github.io/styleguide/javaguide.html 56[well-formed commit message]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html 57 58#### Merging pull requests #### 59 60Due to Guava's nature as a subset of Google's internal codebase which is 61automatically synced to the public GitHub repository, we are unable to merge 62pull requests directly into the master branch. Instead, once a pull request is 63ready for merging, we'll make the appropriate changes in the internal codebase 64and, when the change is synced out, give the pull request author credit for the 65commit. 66 67Contributor License Agreement 68----------------------------- 69 70Contributions to any Google project must be accompanied by a Contributor 71License Agreement. This is not a copyright _assignment_; it simply gives 72Google permission to use and redistribute your contributions as part of the 73project. 74 75 - If you are an individual writing original source code and you're sure you 76 own the intellectual property, then you'll need to sign an [individual 77 CLA][]. Please include your GitHub username. 78 - If you work for a company that wants to allow you to contribute your work, 79 then you'll need to sign a [corporate CLA][]. 80 81You generally only need to submit a CLA once, so if you've already submitted 82one (even if it was for a different project), you probably don't need to do it 83again. 84 85[individual CLA]: https://cla.developers.google.com/about/google-individual 86[corporate CLA]: https://developers.google.com/open-source/cla/corporate 87