Put the Code in (the Right) //third_party

Find the right //third_party

TIP: If you are not on Piper, please see go/thirdparty/non-google3.

In Piper, most third-party code lives in //piper/.../third_party. If your code doesn't belong there and you can't find an appropriate third_party below, file a bug and we'll help you find one. Do NOT create your own project-specific third_party repository without approval. Put packages in an existing location instead.

NOTE: You should put code directly into the package directory and not in a versioned subdirectory. That is //piper/.../... and not //piper/.../.... This does not apply for Java, Haskell, or when you have a go/oneversion exception to have multiple versions.

Approved //third_party code locations

//piper/.../third_party

This is the main //third_party repository, used by anything that builds with google3.

//piper/.../third_party

Special repository for production/monitoring. (Only for legacy borgmon use. No new packages should go here.)

//piper/.../vendor_src and //piper/.../google_vendor_src_branch

Code not built by blaze (such as standalone binaries and .rpm packages), that does not fall into any of the above categories, probably needs to use the go/vendorsrc method. (Currently in pre-deprecation).

Platforms open source locations

//piper/.../patched_vendor_src

Packages used by non-google3 go/platforms-networking code; a variation on the go/vendorsrc method.

//piper/.../patched_vendor_src

Packages used by non-google3 platforms networking hardware go/planethw code; a variation on the go/vendorsrc method.

Finance depot open source locations

//piper/.../third_party

Third party code used in //piper/.../finance applications

Deprecated / deleted

Do not use these locations without explicit approval from third-party-removed- approvers.

NOTE: With the exception of Java and Haskell, you should put your code straight into the package directory, not in a versioned subdirectory. That is, straight into, e.g., //piper/.../... and not into //piper/.../....

Separate out dependencies

Many open source projects include all of their dependencies as part of their repository. This is convenient externally, but in //third_party can cause problems with duplication and license compliance.

We do not permit packages to be nested inside other packages. Strip out all dependencies and import them individually into the appropriate location under //third_party. Many may already exist.

Bundled dependencies can also represent potential security concerns, for example if a vulnerable older version of a library is bundled. In addition to the above, unbundling allows us to properly track compliance with licenses, and monitor or alert about vulnerabilities that may indirectly affect the software you are checking in.

NOTE: On GitHub or in Git-on-Borg projects should follow go/thirdparty/non-google3 and keep their third-party dependencies isolated in a third_party directory. When that project is imported into //piper/.../third_party the contents of that third_party directory should not be copied over directly but each dependency evaluated independently to either be imported or use an existing version.

//third_party subdirectories

go/subdirectories

Most of the time, new third-party packages will go in a new directory under the root of //third_party or in the appropriate language-specific directory. A third-party package usually maps to a single external repository.

On rare occasions, there might be need to group multiple third-party packages under a subdirectory of //third_party. A subdirectory that contains one or more different packages must have a METADATA file with third_party { type:GROUP }.

TIP: If you need to put multiple versions of the same package in a directory, see The One Version Rule for instructions.

If you think you need a type:GROUP directory:

• File a new directory request first to discuss your use case and get it approved.

Once your request has been approved, you must follow the following rules:

• Include a README.md file that explains what the subdirectory is for.
• Include a METADATA file with a third_party { type: GROUP } field linking to the issue approved above.
• The OWNERS file for the subdirectory, if present, must not permit addition of new directories above the individual package level to bypass emailremoved@ review. It should only contain per-file directives. This is to ensure that all new packages go through compliance review.

If packages in the subdirectory will be managed by the same people, it is common to have an OWNERS.team file in the root directory which contains the package maintainers. Then each package's OWNERS file contains a line to include the OWNERS.team file. For example:

//third_party/teleporter/OWNERS.teleporter:

googler1
googler2

//third_party/teleporter/METADATA:

name: "teleporter"
description: "packages related to the teleporter"
third_party {
  type: GROUP
  group {
    approval: "b/12345678"
  }
}

//third_party/teleporter/README.md:

# Goat Teleporter

This directory contains packages related to the open source *Goat
Teleporter*.

It should not contain any packages related to the Cow Teleporter or the
Transporter.

//third_party/teleporter/OWNERS:

per-file METADATA,README.md,OWNERS.teleporter=file:OWNERS.teleporter

//third_party/teleporter/package/OWNERS:

file:../OWNERS.teleporter

TIP: The file directive in OWNERS files in //third_party should point to OWNERS files also within //third_party. Otherwise, Googlers who never touch third-party code may be considered "owners" of third-party code, much to their surprise.

See go/thirdparty/metadata#group for details.

Language Specific Groups

Packages in //third_party/golang or //third_party/py will sometimes be grouped under a common directory to reflect the upstream grouping or namespaces. Such a type:GROUP directory can be approved by third-party-removed as long as it follows the above rules, without requiring a directory request bug.

NEXT: Get the code to work with Google