Skip to content

Latest commit

 

History

History
175 lines (140 loc) · 7.01 KB

CONTRIBUTING.md

File metadata and controls

175 lines (140 loc) · 7.01 KB

How to become a contributor and submit your own code

Contributor License Agreements

We'd love to accept your patches! Before we can take them, we have to jump a couple of legal hurdles.

Please fill out either the individual or corporate Contributor License Agreement (CLA).

  • If you are an individual writing original source code and you're sure you own the intellectual property, then you'll need to sign an individual CLA.
  • If you work for a company that wants to allow you to contribute your work, then you'll need to sign a corporate CLA.

Follow either of the two links above to access the appropriate CLA and instructions for how to sign and return it. Once we receive it, we'll be able to accept your pull requests.

Contributing A Patch

  1. Submit an issue describing your proposed change to the repo in question.
  2. The repo owner will respond to your issue promptly.
  3. If your proposed change is accepted, and you haven't already done so, sign a Contributor License Agreement (see details above).
  4. Fork the desired repo, develop and test your code changes.
  5. Ensure that your code adheres to the existing style in the sample to which you are contributing.
  6. Ensure that your code has an appropriate set of unit tests which all pass.
  7. Submit a pull request.

Style

This repository follow the Google C++ Style Guide. Please make sure your contributions adhere to the style guide.

Formatting

The code in this project is formatted with clang-format(1), and our CI builds will check that the code matches the format generated by this tool before accepting a pull request. Please configure your editor or IDE to use the Google style for indentation and other whitespace. If you need to reformat one or more files, you can simply run clang-format manually:

$ clang-format -i <file>....

Reformatting all the files in a specific directory should be safe too, for example:

$ find bigtable -o -name '*.h' -o -name '*.cc' -print0 \
    | xargs -0 clang-format -i

If you need to reformat one of the files to match the Google style. Please be advised that clang-format has been known to generate slightly different formatting in different versions, we use version 4.0, use the same version if you run into problems.

If you have prepared a Docker image for ubuntu:17.10 (see below), you can verify and fix the format of your code using:

# Run from google-cloud-cpp:
$ TRAVIS_OS_NAME=linux DISTRO=ubuntu DISTRO_VERSION=17.10 CXX=clang++ CC=clang CHECK_STYLE=yes ./ci/build-linux.sh

Advanced Compilation and Testing

Please see the README for the basic instructions on how to compile the code. In this section we will describe some advanced options.

Changing the Compiler

If your workstation has multiple compilers (or multiple versions of a compiler) installed, you can change the compiler using:

# Run this in your build directory, typically google-cloud-cpp/.build
$ CXX=clang++ CC=clang cmake ..

# Then compile and test normally:
$ make -j 4
$ make -j 4 test

Changing the Build Type

By default, the system is compiled with optimizations on; if you want to compile a debug version, use:

# Run this in your build directory, typically google-cloud-cpp/.build
$ CXX=clang++ CC=clang cmake -DCMAKE_BUILD_TYPE=Debug ..

# Then compile and test normally:
$ make -j 4
$ make -j 4 test

This project supports Debug, Release, and Coverage builds.

Using Docker to Compile and Test

This project uses Docker in its CI builds to test against multiple Linux distributions, using the native compiler and library versions included in those distributions. From time to time, you may need to run the same build on your workstation. To do so, install Docker on your workstation, then create the build Docker image for the environment you intend to use, for example:

# Run from the google-cloud-cpp directory.
$ TRAVIS_OS_NAME=linux DISTRO=ubuntu DISTRO_VERSION=17.10 ./ci/install-linux.sh

Once you create the image for a given combination of DISTRO and DISTRO_VERSION, you can compile the code multiple times, for example:

# Also run from google-cloud-cpp:
$ TRAVIS_OS_NAME=linux DISTRO=ubuntu DISTRO_VERSION=17.10 CXX=clang++ CC=clang BUILD_TYPE=Debug ./ci/build-linux.sh

You can set any of the following environment variables to control the build. Please consult the build matrix in your .travis.yml file to see which combinations are tested regularly.

  • CXX: the C++ compiler, you can use a full path if needed.
  • CC: the C compiler, you can use a full path if needed. Typically you set both variables to select the compiler. For example:
    • CXX=clang++ CC=clang to use Clang.
    • CXX=g++ CC=gcc to use GCC.
  • DISTRO: the Linux distribution, use ubuntu, fedora, or centos.
  • DISTRO_VERSION: the version of the distribution, e.g. 16.04.
  • CHECK_STYLE: if set to yes, the build fails if the code is different than the output from clang-format(1). Note that this reformats your files, that can be useful to keep the formatting clean.
  • GENERATE_DOCS: if set to yes the build will generate the documentation using Doxygen. In addition, if GH_TOKEN is set it will try to update the gh-pages branch on your fork with the new documentation.
  • BUILD_TYPE: if set, override the CMAKE_BUILD_TYPE flag when configuring the build.
  • SCAN_BUILD: if set to yes, use Clang static analyzer (aka scan-build) to compile the code. Remember to also set the compiler to Clang as described above. Builds with this configuration can be substantially slower.
  • CMAKE_FLAGS: if set, these additional cmake flags are used to configure the build. The more interesting flags include:
    • -DSANITIZE_ADDRESS=yes: use the AddressSanitizer, if available, on this build.
    • -DSANITIZE_UNDEFINED=yes: use the UndefinedBehaviorSanitizer, if available, on this build.
    • -DSANITIZE_THREAD=yes: use the ThreadSanitizer, if available, on this build.
    • -DSANITIZE_MEMORY=yes: use the MemorySanitizer, if available, on this build. This is rarely used because it requires a C++ library compiled with the same options to avoid false positives.
    • All the sanitizers require Clang, remember to select the compiler as described above.
  • -DBIGTABLE_CLIENT_CLANG_TIDY=yes: configure the build to run clang-tidy for the code in the bigtable/ subdirectory. Check the configuration file for details on what clang-tidy options we use.