gps-building-blocks 1.2.1

Modules and tools useful for use with advanced data solutions on Google Ads, Google Marketing Platform and Google Cloud.

gPS Solutions - Core Libraries Repository

go/gPS-BB-doc

NOTE: This is the internal documentation for the gps_building_blocks repository and should be used for any content that we do not want to publicize. The external documentation can be found here and should only contain external-friendly information pertaining to the repository contents.

This repository utilizes Copybara{target="_blank"} to sync its state between google3, Git-on-Borg and GitHub (repo links can be found below). As a result, a few things need to be taken into consideration to allow copybara to work properly. The following sections provide instructions for gPS BB internal contributors.

Note: For more information on configuring copybara and its different workflows, refer to the documentation at go/gPS-BB-copybara.

Commit Messages {#commit-message}

Wrap the CL description you would like to appear on Git-on-Borg and/or GitHub with the tags: BEGIN_PUBLIC and END_PUBLIC. Alternatively, use PUBLIC: for single-line comments. If you do not add the OSS tags properly the commit message will be exported as Internal Change. For more information, refer to the copybara documentation here{target="_blank"}.

Commit authors

If you want your name and email to appear as author of the external commits on GitHub, add your GitHub account to the whitelisted_authors element on the copybara configuration file. You may also want to consider adding yourself into the username_mapping element if you want your ldap to be translated into your GitHub username throughout the code.

Source Code Files

All source code files must start with the correct license agreement. This is one of the OSS requirements imposed by Google (see go/releasing/preparing#license-headers). Please use the addlicense{target="_blank"} tool for including the license header. Here is an example for adding the Apache 2.0 license to all source code files in the current directory:
go get -u github.com/google/addlicense && ~/go/bin/addlicense -l apache .

Note: This command is idempotent; it will not add the license to files that already have it. Beware however since it will not take into consideration any excluded files listed in the copybara configuration. So make sure you review all modified files after running the script and revert anyundesired chages.

Usage of google3 Libraries

Please be careful when explicitly referencing internal google3 libraries in your python files (e.g. from google3.xxx or import google3.xxx), since these libraries may not be publicly available. There are primarily two ways of mitigating this:

• Modify your BUILD file so that google3 dependencies are implicitly referenced (e.g. import google3.third_party.py.googleapiclient becomes import googleapiclient). See go/py-strict-deps for more information
• Explicitly add a transform element to the py_transforms array in the copybara configuration file to convert the internal library path into its external-friendly one

Usage of googletest vs. unittest

Copybara will automatically change from google3.testing.pybase import googletest to import unittest for export workflows, and vice-versa for imports. Therefore please be consistent and always use from google3.testing.pybase import googletest internally instead of import unittest.

Language Level READMEs

Each language has its own README to cover language level nuances. Please review the appropriate language documentation.

• Python

  IMPORTANT: If you are writing a new module that relies on APIs, please read about external dependency management.

Testing changes locally

Copybara offers a presubmit service through which you can test both your file content and commit message transformations. This can be triggered for a pending CL by executing copybara <path to copy.bara.sky> presubmit_piper_to_gerrit <cl number>. This will create a Gerrit change in the Git-on-Borg gPS Bulding Blocks repo, which you should abandon once your test is complete (since Copybara-as-a-Service will migrate the change for you automatically). When adding the --dry-run flag to this command, the Gerrit change will be skipped and instead the metadata of the change (i.e. no file changes, only commit message and history) will be synced to a local temp git repo (non-work tree).

Rejecting Public Contributions

If you would like to reject a public contribution, consider commenting directly on the GitHub PR and/or closing the PR altogether. You can also abandon the automatically generated change in the Gerrit safe review. If the Gerrit change had already been approved and a resulting CL was created in Piper, you will not be able to revert the CL, since it is owned by the copybara worker. However, such CLs will automatically be garbage collected by the copybara worker if they have not been updated for a week (see reference documentation here).

Note: You can now{target="_blank"} use the tag #DELETE_CL in a comment (not a reply) and the CL will be deleted on a best effort basis, usually within minutes.

See Also

• The Building Blocks Project also has a directory in //corp/gtech/ads which is intended to be internal to the CSE/DS team
• Buganizer Component for filing issues, etc.
• Git-on-Borg repository {target="_blank"}
• GitHub repository {target="_blank"}