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 athird_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 containper-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.