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