Get the Code

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

We already have many libraries and tools in //third_party. Try codesearch to find the code you're thinking of. If we do have it, go ahead and start using it. If we have an older version, feel free to upgrade the code, coordinating with the current OWNERS (up to and including adding yourself as an OWNER if the package is not being actively maintained). Before checking in a new package, consider the maintenance responsibilities you are agreeing to when adding a new package vs. trying to use an existing package that provides the functionality you are looking for.

When packages that perform the same function proliferate in //third_party, they tend to skew widely in quality and maintenance over time. By aligning around a single package to provide a common need, you help your team avoid future cleanup efforts and churn and allows Google to focus on maintaining the single best package for a particular purpose around.

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.

TIP: The code does not have to build during the initial import.

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; transformations applied by copybara may be included in the initial CL and the patched code will still be considered "pristine" for this purpose.

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).

Adding new, wholly authored Google files, is also OK.

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.

Subsequent version update CLs performed for a previously imported package do not require a pristine copy; any necessary local modifications should be included in the update.

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