|
| 1 | +# How to become a contributor and submit your own code |
| 2 | + |
| 3 | +## Contributor License Agreements |
| 4 | + |
| 5 | +We'd love to accept your patches! Before we can take them, we |
| 6 | +have to jump a couple of legal hurdles. |
| 7 | + |
| 8 | +Please fill out either the individual or corporate Contributor License Agreement |
| 9 | +(CLA). |
| 10 | + |
| 11 | + * If you are an individual writing original source code and you're sure you |
| 12 | + own the intellectual property, then you'll need to sign an |
| 13 | + [individual CLA](https://developers.google.com/open-source/cla/individual). |
| 14 | + * If you work for a company that wants to allow you to contribute your work, |
| 15 | + then you'll need to sign a |
| 16 | + [corporate CLA](https://developers.google.com/open-source/cla/corporate). |
| 17 | + |
| 18 | +Follow either of the two links above to access the appropriate CLA and |
| 19 | +instructions for how to sign and return it. Once we receive it, we'll be able to |
| 20 | +accept your pull requests. |
| 21 | + |
| 22 | +## Contributing A Patch |
| 23 | + |
| 24 | +1. Submit an issue describing your proposed change to the |
| 25 | + [issue tracker](https://github.com/google/googletest). |
| 26 | +1. Please don't mix more than one logical change per submittal, |
| 27 | + because it makes the history hard to follow. If you want to make a |
| 28 | + change that doesn't have a corresponding issue in the issue |
| 29 | + tracker, please create one. |
| 30 | +1. Also, coordinate with team members that are listed on the issue in |
| 31 | + question. This ensures that work isn't being duplicated and |
| 32 | + communicating your plan early also generally leads to better |
| 33 | + patches. |
| 34 | +1. If your proposed change is accepted, and you haven't already done so, sign a |
| 35 | + Contributor License Agreement (see details above). |
| 36 | +1. Fork the desired repo, develop and test your code changes. |
| 37 | +1. Ensure that your code adheres to the existing style in the sample to which |
| 38 | + you are contributing. |
| 39 | +1. Ensure that your code has an appropriate set of unit tests which all pass. |
| 40 | +1. Submit a pull request. |
| 41 | + |
| 42 | +If you are a Googler, it is preferable to first create an internal change and |
| 43 | +have it reviewed and submitted, and then create an upstreaming pull |
| 44 | +request here. |
| 45 | + |
| 46 | +## The Google Test and Google Mock Communities ## |
| 47 | + |
| 48 | +The Google Test community exists primarily through the |
| 49 | +[discussion group](http://groups.google.com/group/googletestframework) |
| 50 | +and the GitHub repository. |
| 51 | +Likewise, the Google Mock community exists primarily through their own |
| 52 | +[discussion group](http://groups.google.com/group/googlemock). |
| 53 | +You are definitely encouraged to contribute to the |
| 54 | +discussion and you can also help us to keep the effectiveness of the |
| 55 | +group high by following and promoting the guidelines listed here. |
| 56 | + |
| 57 | +### Please Be Friendly ### |
| 58 | + |
| 59 | +Showing courtesy and respect to others is a vital part of the Google |
| 60 | +culture, and we strongly encourage everyone participating in Google |
| 61 | +Test development to join us in accepting nothing less. Of course, |
| 62 | +being courteous is not the same as failing to constructively disagree |
| 63 | +with each other, but it does mean that we should be respectful of each |
| 64 | +other when enumerating the 42 technical reasons that a particular |
| 65 | +proposal may not be the best choice. There's never a reason to be |
| 66 | +antagonistic or dismissive toward anyone who is sincerely trying to |
| 67 | +contribute to a discussion. |
| 68 | + |
| 69 | +Sure, C++ testing is serious business and all that, but it's also |
| 70 | +a lot of fun. Let's keep it that way. Let's strive to be one of the |
| 71 | +friendliest communities in all of open source. |
| 72 | + |
| 73 | +As always, discuss Google Test in the official GoogleTest discussion group. |
| 74 | +You don't have to actually submit code in order to sign up. Your participation |
| 75 | +itself is a valuable contribution. |
| 76 | + |
| 77 | +## Style |
| 78 | + |
| 79 | +To keep the source consistent, readable, diffable and easy to merge, |
| 80 | +we use a fairly rigid coding style, as defined by the [google-styleguide](https://github.com/google/styleguide) project. All patches will be expected |
| 81 | +to conform to the style outlined [here](https://google.github.io/styleguide/cppguide.html). |
| 82 | + |
| 83 | +## Requirements for Contributors ### |
| 84 | + |
| 85 | +If you plan to contribute a patch, you need to build Google Test, |
| 86 | +Google Mock, and their own tests from a git checkout, which has |
| 87 | +further requirements: |
| 88 | + |
| 89 | + * [Python](https://www.python.org/) v2.3 or newer (for running some of |
| 90 | + the tests and re-generating certain source files from templates) |
| 91 | + * [CMake](https://cmake.org/) v2.6.4 or newer |
| 92 | + * [GNU Build System](https://en.wikipedia.org/wiki/GNU_Build_System) |
| 93 | + including automake (>= 1.9), autoconf (>= 2.59), and |
| 94 | + libtool / libtoolize. |
| 95 | + |
| 96 | +## Developing Google Test ## |
| 97 | + |
| 98 | +This section discusses how to make your own changes to Google Test. |
| 99 | + |
| 100 | +### Testing Google Test Itself ### |
| 101 | + |
| 102 | +To make sure your changes work as intended and don't break existing |
| 103 | +functionality, you'll want to compile and run Google Test's own tests. |
| 104 | +For that you can use CMake: |
| 105 | + |
| 106 | + mkdir mybuild |
| 107 | + cd mybuild |
| 108 | + cmake -Dgtest_build_tests=ON ${GTEST_DIR} |
| 109 | + |
| 110 | +Make sure you have Python installed, as some of Google Test's tests |
| 111 | +are written in Python. If the cmake command complains about not being |
| 112 | +able to find Python (`Could NOT find PythonInterp (missing: |
| 113 | +PYTHON_EXECUTABLE)`), try telling it explicitly where your Python |
| 114 | +executable can be found: |
| 115 | + |
| 116 | + cmake -DPYTHON_EXECUTABLE=path/to/python -Dgtest_build_tests=ON ${GTEST_DIR} |
| 117 | + |
| 118 | +Next, you can build Google Test and all of its own tests. On \*nix, |
| 119 | +this is usually done by 'make'. To run the tests, do |
| 120 | + |
| 121 | + make test |
| 122 | + |
| 123 | +All tests should pass. |
| 124 | + |
| 125 | +### Regenerating Source Files ## |
| 126 | + |
| 127 | +Some of Google Test's source files are generated from templates (not |
| 128 | +in the C++ sense) using a script. |
| 129 | +For example, the |
| 130 | +file include/gtest/internal/gtest-type-util.h.pump is used to generate |
| 131 | +gtest-type-util.h in the same directory. |
| 132 | + |
| 133 | +You don't need to worry about regenerating the source files |
| 134 | +unless you need to modify them. You would then modify the |
| 135 | +corresponding `.pump` files and run the '[pump.py](googletest/scripts/pump.py)' |
| 136 | +generator script. See the [Pump Manual](googletest/docs/PumpManual.md). |
| 137 | + |
| 138 | +## Developing Google Mock ### |
| 139 | + |
| 140 | +This section discusses how to make your own changes to Google Mock. |
| 141 | + |
| 142 | +#### Testing Google Mock Itself #### |
| 143 | + |
| 144 | +To make sure your changes work as intended and don't break existing |
| 145 | +functionality, you'll want to compile and run Google Test's own tests. |
| 146 | +For that you'll need Autotools. First, make sure you have followed |
| 147 | +the instructions above to configure Google Mock. |
| 148 | +Then, create a build output directory and enter it. Next, |
| 149 | + |
| 150 | + ${GMOCK_DIR}/configure # try --help for more info |
| 151 | + |
| 152 | +Once you have successfully configured Google Mock, the build steps are |
| 153 | +standard for GNU-style OSS packages. |
| 154 | + |
| 155 | + make # Standard makefile following GNU conventions |
| 156 | + make check # Builds and runs all tests - all should pass. |
| 157 | + |
| 158 | +Note that when building your project against Google Mock, you are building |
| 159 | +against Google Test as well. There is no need to configure Google Test |
| 160 | +separately. |
0 commit comments