opensource.google.com

Menu

Docs

Get the Code

go/thirdparty/retrieving

Make sure we don’t already have the code in //third_party

We already have many libraries and tools in //third_party. Try go/cs to find the code you’re thinking of. If we do have it, just start using it. If we have an older version, feel free to upgrade the code (coordinating with the current OWNERS).

Get the code

When you find code or libraries you want to use, get the source code. For Open Source packages, this is often easy, you can get it from GitHub or somewhere else. For commercial packages, this can sometimes mean negotiating a license with another company and receiving the code another way.

When we say get the code, we mean it. You really don’t want to have a binary library in //third_party. They break often. When they break, you get to keep both pieces (that is, they are completely the responsibility and burden of the team that owns them, and we will not block any other team from doing things that break them). There are also security implications of using a binary where you can’t verify the source. If you aren’t willing to pay the cost of maintaining the code at Google, you generally should not be using the library. Every binary library that has ever been in third party has been a maintenance problem for that team, and they are STRONGLY discouraged.

If, for whatever reason, you still must check a binary into //third_party, they are expected to be able to meet the go/build-horizon policy and be recompilable on demand.

Pristine copy

go/pristinecopy

The first CL should be the version of the code as it was initially downloaded. This allows us to track changes and to revert back to the unedited version if need be. (E.g., reverting a workaround for a Google-specific quirk once that quirk has been removed.)

To facilitate this, you may want to make a copy of the code in another client. It’s a good idea (but not strictly necessary) to bring in any tests included in the package. You don’t have to include unused files and feel free to move or rename files, but do not modify the contents of any files, unless otherwise noted below.

Exceptions

If you’re using go/copybara to manage your project (which is recommended when possible) your initial CL must contain a copy of the code along with the assorted metadata files—BUILD, LICENSE, copy.bara.sky, etc. If you need to patch something, use copybara transformations.

Some language-specific policies permit or require modifying some files (e.g., Go’s update.go supports patches in a similar way to Copybara, and JavaScript requires @license annotations even in pristine copies).

Next steps

Alongside the code, the first CL must contain the various metadata files used internally: OWNERS, BUILD, LICENSE, and METADATA. See go/thirdparty/documentation for details.

Please add only one new package per changelist. If you want to import multiple packages, split them into individual CLs, one per package.

For example, package foo from https://github.com/mux/foo relies upon package bar from https://github.com/frob/bar. Package foo is in one CL and resides in //third_party/py/foo while package bar is in a separate CL and resides in //third_party/py/bar.

The review auto-assigner will assign each CL as soon as it’s mailed, so the reviews will proceed in parallel.

NEXT: Put the code in (the right) //third_party

Except as otherwise noted, the content of this page is licensed under CC-BY-4.0 license. Third-party product names and logos may be the trademarks of their respective owners.