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.
- Submit an issue describing your proposed change to the repo in question.
- The repo owner will respond to your issue promptly.
- If your proposed change is accepted, and you haven't already done so, sign a Contributor License Agreement (see details above).
- Fork the desired repo, develop and test your code changes.
- Ensure that your code adheres to the existing style in the sample to which you are contributing.
- Ensure that your code has an appropriate set of unit tests which all pass.
- Submit a pull request.
If you are just getting started with git
and GitHub,
this section might be helpful. In this project we use the (more or less)
standard GitHub workflow:
- You create a fork of google-cloud-cpp. Then
clone that fork into your workstation:
git clone git@github.com:YOUR-USER-NAME/google-cloud-cpp.git
- The cloned repo that you created in the previous step will have its
origin
set to your forked repo. You should now tell git about the the mainupstream
repo, which you'll use to pull commits made by others in order to keep your local repo and fork up to date.git remote add upstream git@github.com:GoogleCloudPlatform/google-cloud-cpp.git git remote -v # Should show 'origin' (your fork) and 'upstream' (main repo)
- To pull new commits from
upstream
into your local repo and sync your fork you can do the following:Note: You probably want to do this periodically, and almost certainly before starting your next task.git checkout master git pull --ff-only upstream master git push # Pushes new commits up to your fork on GitHub
- You pick an existing GitHub bug to work on.
- You start a new branch for each feature (or bug fix).
git checkout master git checkout -b my-feature-branch git push -u origin my-feature-branch # Tells fork on GitHub about new branch # make your changes git push
- You submit a pull-request to merge your branch into
GoogleCloudPlatform/google-cloud-cpp
. - Your reviewers may ask questions, suggest improvements or alternatives. You
address those by either answering the questions in the review or adding more
commits to your branch and
git push
-ing those commits to your fork. - From time to time your pull request may have conflicts with the destination
branch (likely
master
), if so, we request that you rebase your branch instead of merging. The reviews can become very confusing if you merge during a pull request. You should first ensure that yourmaster
branch has all the latest commits by syncing your fork (see above), then do the following:git checkout my-feature-branch git rebase master git push --force-with-lease
- If one of the CI builds fail please see below, most of the CI builds can be reproduced locally on your workstations using Docker.
- Eventually the reviewers accept your changes, and they are merged into the
master
branch.
This repository follow the Google C++ Style Guide. Please make sure your contributions adhere to the style guide.
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 google/cloud -o -name '*.h' -o -name '*.cc' -print0 \
| xargs -0 clang-format -i
You might find it convenient to reformat only the files that you added or modified:
$ git status -s \
| awk 'NF>1{print $NF}' \
| grep -E '.*\.(cc|h)$' \
| while read fpath; do if [ -f "$fpath" ]; then echo "$fpath"; fi; done \
| xargs 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 6.0; use the same version if
you run into problems.
If you have prepared a Docker image for ubuntu:18.04
(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=18.04 \
CXX=clang++ CC=clang CHECK_STYLE=yes ./ci/travis/build-linux.sh
If you need to change the list of files associated with a library, please change
the existing CMakeLists.txt
files, even if you use Bazel as your preferred
build system. Changing the CMake files automatically update the corresponding
.bzl
files, but changing the .bzl
files will not. More details in the short
design doc.
Please see the README for the basic instructions on how to compile the code. In this section we will describe some advanced options.
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
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.
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=18.04 ./ci/travis/install-linux.sh
Once you create the image for a given combination of DISTRO
and
DISTRO_VERSION
, you can reuse it for many builds, with different options.
For example, this (rather longish)
command will verify that your code is formatted correctly, run the
clang-tidy(1) checks, verify the Doxygen documentation can be generated, and run
both the unit and integration tests:
CHECK_STYLE=yes GENERATE_DOCS=yes \
CMAKE_FLAGS=-DGOOGLE_CLOUD_CPP_CLANG_TIDY=yes \
DISTRO=ubuntu DISTRO_VERSION=18.04 CXX=clang++ CC=clang NCPU=$(nproc) \
TRAVIS_OS_NAME=linux ./ci/travis/build-linux.sh
You may want to add BUILD_TYPE=Debug
to the list of environment variables,
as the default (BUILD_TYPE=Release
) may be slightly slower.
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, useubuntu
,fedora
, orcentos
.DISTRO_VERSION
: the version of the distribution, e.g.16.04
.CHECK_STYLE
: if set toyes
, the build fails if the code is different than the output fromclang-format(1)
. Note that this reformats your files, that can be useful to keep the formatting clean.GENERATE_DOCS
: if set toyes
the build will generate the documentation using Doxygen. In addition, ifGH_TOKEN
is set it will try to update thegh-pages
branch on your fork with the new documentation.BUILD_TYPE
: if set, override theCMAKE_BUILD_TYPE
flag when configuring the build.BUILD_TESTING
: if set tono
, disable the unit tests. This is sometimes useful for package maintainers that may want to reduce their build times.SCAN_BUILD
: if set toyes
, use Clang static analyzer (akascan-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.
-DGOOGLE_CLOUD_CPP_CLANG_TIDY=yes
: configure the build to runclang-tidy
for the Google Cloud C++ Libraries. Check the configuration file for details on whatclang-tidy
options we use.CREATE_GRAPHVIZ
: if set toyes
, useCMake
to generate a dependency graph of each target. This is useful when troubleshooting dependencies, or simply when trying to document them.