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