1*a6aa18fbSYabin Cui# How to Contribute to Abseil 2*a6aa18fbSYabin Cui 3*a6aa18fbSYabin CuiWe'd love to accept your patches and contributions to this project. There are 4*a6aa18fbSYabin Cuijust a few small guidelines you need to follow. 5*a6aa18fbSYabin Cui 6*a6aa18fbSYabin CuiNOTE: If you are new to GitHub, please start by reading [Pull Request 7*a6aa18fbSYabin Cuihowto](https://help.github.com/articles/about-pull-requests/) 8*a6aa18fbSYabin Cui 9*a6aa18fbSYabin Cui## Contributor License Agreement 10*a6aa18fbSYabin Cui 11*a6aa18fbSYabin CuiContributions to this project must be accompanied by a Contributor License 12*a6aa18fbSYabin CuiAgreement. You (or your employer) retain the copyright to your contribution, 13*a6aa18fbSYabin Cuithis simply gives us permission to use and redistribute your contributions as 14*a6aa18fbSYabin Cuipart of the project. Head over to <https://cla.developers.google.com/> to see 15*a6aa18fbSYabin Cuiyour current agreements on file or to sign a new one. 16*a6aa18fbSYabin Cui 17*a6aa18fbSYabin CuiYou generally only need to submit a CLA once, so if you've already submitted one 18*a6aa18fbSYabin Cui(even if it was for a different project), you probably don't need to do it 19*a6aa18fbSYabin Cuiagain. 20*a6aa18fbSYabin Cui 21*a6aa18fbSYabin Cui## Contribution Guidelines 22*a6aa18fbSYabin Cui 23*a6aa18fbSYabin CuiPotential contributors sometimes ask us if the Abseil project is the appropriate 24*a6aa18fbSYabin Cuihome for their utility library code or for specific functions implementing 25*a6aa18fbSYabin Cuimissing portions of the standard. Often, the answer to this question is "no". 26*a6aa18fbSYabin CuiWe’d like to articulate our thinking on this issue so that our choices can be 27*a6aa18fbSYabin Cuiunderstood by everyone and so that contributors can have a better intuition 28*a6aa18fbSYabin Cuiabout whether Abseil might be interested in adopting a new library. 29*a6aa18fbSYabin Cui 30*a6aa18fbSYabin Cui### Priorities 31*a6aa18fbSYabin Cui 32*a6aa18fbSYabin CuiAlthough our mission is to augment the C++ standard library, our goal is not to 33*a6aa18fbSYabin Cuiprovide a full forward-compatible implementation of the latest standard. For us 34*a6aa18fbSYabin Cuito consider a library for inclusion in Abseil, it is not enough that a library 35*a6aa18fbSYabin Cuiis useful. We generally choose to release a library when it meets at least one 36*a6aa18fbSYabin Cuiof the following criteria: 37*a6aa18fbSYabin Cui 38*a6aa18fbSYabin Cui* **Widespread usage** - Using our internal codebase to help gauge usage, most 39*a6aa18fbSYabin Cui of the libraries we've released have tens of thousands of users. 40*a6aa18fbSYabin Cui* **Anticipated widespread usage** - Pre-adoption of some standard-compliant 41*a6aa18fbSYabin Cui APIs may not have broad adoption initially but can be expected to pick up 42*a6aa18fbSYabin Cui usage when it replaces legacy APIs. `absl::from_chars`, for example, 43*a6aa18fbSYabin Cui replaces existing code that converts strings to numbers and will therefore 44*a6aa18fbSYabin Cui likely see usage growth. 45*a6aa18fbSYabin Cui* **High impact** - APIs that provide a key solution to a specific problem, 46*a6aa18fbSYabin Cui such as `absl::FixedArray`, have higher impact than usage numbers may signal 47*a6aa18fbSYabin Cui and are released because of their importance. 48*a6aa18fbSYabin Cui* **Direct support for a library that falls under one of the above** - When we 49*a6aa18fbSYabin Cui want access to a smaller library as an implementation detail for a 50*a6aa18fbSYabin Cui higher-priority library we plan to release, we may release it, as we did 51*a6aa18fbSYabin Cui with portions of `absl/meta/type_traits.h`. One consequence of this is that 52*a6aa18fbSYabin Cui the presence of a library in Abseil does not necessarily mean that other 53*a6aa18fbSYabin Cui similar libraries would be a high priority. 54*a6aa18fbSYabin Cui 55*a6aa18fbSYabin Cui### API Freeze Consequences 56*a6aa18fbSYabin Cui 57*a6aa18fbSYabin CuiVia the 58*a6aa18fbSYabin Cui[Abseil Compatibility Guidelines](https://abseil.io/about/compatibility), we 59*a6aa18fbSYabin Cuihave promised a large degree of API stability. In particular, we will not make 60*a6aa18fbSYabin Cuibackward-incompatible changes to released APIs without also shipping a tool or 61*a6aa18fbSYabin Cuiprocess that can upgrade our users' code. We are not yet at the point of easily 62*a6aa18fbSYabin Cuireleasing such tools. Therefore, at this time, shipping a library establishes an 63*a6aa18fbSYabin CuiAPI contract which is borderline unchangeable. (We can add new functionality, 64*a6aa18fbSYabin Cuibut we cannot easily change existing behavior.) This constraint forces us to 65*a6aa18fbSYabin Cuivery carefully review all APIs that we ship. 66*a6aa18fbSYabin Cui 67*a6aa18fbSYabin Cui 68*a6aa18fbSYabin Cui## Coding Style 69*a6aa18fbSYabin Cui 70*a6aa18fbSYabin CuiTo keep the source consistent, readable, diffable and easy to merge, we use a 71*a6aa18fbSYabin Cuifairly rigid coding style, as defined by the 72*a6aa18fbSYabin Cui[google-styleguide](https://github.com/google/styleguide) project. All patches 73*a6aa18fbSYabin Cuiwill be expected to conform to the style outlined 74*a6aa18fbSYabin Cui[here](https://google.github.io/styleguide/cppguide.html). 75*a6aa18fbSYabin Cui 76*a6aa18fbSYabin Cui## Guidelines for Pull Requests 77*a6aa18fbSYabin Cui 78*a6aa18fbSYabin Cui* If you are a Googler, it is preferable to first create an internal CL and 79*a6aa18fbSYabin Cui have it reviewed and submitted. The code propagation process will deliver 80*a6aa18fbSYabin Cui the change to GitHub. 81*a6aa18fbSYabin Cui 82*a6aa18fbSYabin Cui* Create **small PRs** that are narrowly focused on **addressing a single 83*a6aa18fbSYabin Cui concern**. We often receive PRs that are trying to fix several things at a 84*a6aa18fbSYabin Cui time, but if only one fix is considered acceptable, nothing gets merged and 85*a6aa18fbSYabin Cui both author's & review's time is wasted. Create more PRs to address 86*a6aa18fbSYabin Cui different concerns and everyone will be happy. 87*a6aa18fbSYabin Cui 88*a6aa18fbSYabin Cui* For speculative changes, consider opening an [Abseil 89*a6aa18fbSYabin Cui issue](https://github.com/abseil/abseil-cpp/issues) and discussing it first. 90*a6aa18fbSYabin Cui If you are suggesting a behavioral or API change, consider starting with an 91*a6aa18fbSYabin Cui [Abseil proposal template](ABSEIL_ISSUE_TEMPLATE.md). 92*a6aa18fbSYabin Cui 93*a6aa18fbSYabin Cui* Provide a good **PR description** as a record of **what** change is being 94*a6aa18fbSYabin Cui made and **why** it was made. Link to a GitHub issue if it exists. 95*a6aa18fbSYabin Cui 96*a6aa18fbSYabin Cui* Don't fix code style and formatting unless you are already changing that 97*a6aa18fbSYabin Cui line to address an issue. Formatting of modified lines may be done using 98*a6aa18fbSYabin Cui `git clang-format`. PRs with irrelevant changes won't be merged. If 99*a6aa18fbSYabin Cui you do want to fix formatting or style, do that in a separate PR. 100*a6aa18fbSYabin Cui 101*a6aa18fbSYabin Cui* Unless your PR is trivial, you should expect there will be reviewer comments 102*a6aa18fbSYabin Cui that you'll need to address before merging. We expect you to be reasonably 103*a6aa18fbSYabin Cui responsive to those comments, otherwise the PR will be closed after 2-3 104*a6aa18fbSYabin Cui weeks of inactivity. 105*a6aa18fbSYabin Cui 106*a6aa18fbSYabin Cui* Maintain **clean commit history** and use **meaningful commit messages**. 107*a6aa18fbSYabin Cui PRs with messy commit history are difficult to review and won't be merged. 108*a6aa18fbSYabin Cui Use `rebase -i upstream/master` to curate your commit history and/or to 109*a6aa18fbSYabin Cui bring in latest changes from master (but avoid rebasing in the middle of a 110*a6aa18fbSYabin Cui code review). 111*a6aa18fbSYabin Cui 112*a6aa18fbSYabin Cui* Keep your PR up to date with upstream/master (if there are merge conflicts, 113*a6aa18fbSYabin Cui we can't really merge your change). 114*a6aa18fbSYabin Cui 115*a6aa18fbSYabin Cui* **All tests need to be passing** before your change can be merged. We 116*a6aa18fbSYabin Cui recommend you **run tests locally** (see below) 117*a6aa18fbSYabin Cui 118*a6aa18fbSYabin Cui* Exceptions to the rules can be made if there's a compelling reason for doing 119*a6aa18fbSYabin Cui so. That is - the rules are here to serve us, not the other way around, and 120*a6aa18fbSYabin Cui the rules need to be serving their intended purpose to be valuable. 121*a6aa18fbSYabin Cui 122*a6aa18fbSYabin Cui* All submissions, including submissions by project members, require review. 123*a6aa18fbSYabin Cui 124*a6aa18fbSYabin Cui## Running Tests 125*a6aa18fbSYabin Cui 126*a6aa18fbSYabin CuiIf you have [Bazel](https://bazel.build/) installed, use `bazel test 127*a6aa18fbSYabin Cui--test_tag_filters="-benchmark" ...` to run the unit tests. 128*a6aa18fbSYabin Cui 129*a6aa18fbSYabin CuiIf you are running the Linux operating system and have 130*a6aa18fbSYabin Cui[Docker](https://www.docker.com/) installed, you can also run the `linux_*.sh` 131*a6aa18fbSYabin Cuiscripts under the `ci/`(https://github.com/abseil/abseil-cpp/tree/master/ci) 132*a6aa18fbSYabin Cuidirectory to test Abseil under a variety of conditions. 133*a6aa18fbSYabin Cui 134*a6aa18fbSYabin Cui## Abseil Committers 135*a6aa18fbSYabin Cui 136*a6aa18fbSYabin CuiThe current members of the Abseil engineering team are the only committers at 137*a6aa18fbSYabin Cuipresent. 138*a6aa18fbSYabin Cui 139*a6aa18fbSYabin Cui## Release Process 140*a6aa18fbSYabin Cui 141*a6aa18fbSYabin CuiAbseil lives at head, where latest-and-greatest code can be found. 142