opensource.google.com

Menu

Docs

Document the Code and its Context

go/thirdparty/documentation

When you submit the code, there needs to be enough context and background to help us with the requirements for //third_party. To that end, we require some metadata be associated with the code. The metadata is sprinkled among a few different files.

  1. OWNERS File
  2. BUILD File
  3. LICENSE File
  4. METADATA File

OWNERS file

go/thirdparty/documentation#owners
Lint warnings: go/thirdparty/linter#owners

The OWNERS file must list at least two full-time Googlers explicitly. The two full-time Googlers must be the first two listed in the OWNERS file. (Owners tagged as cleanup-approver or approve-only satisfy this requirement.) Afterwards, additional owners may be listed as desired.

The exceptions to this rule are:

  • Linking to another OWNERS file within third_party using the file:<file> syntax is allowed. (go/owners#file)
  • Other language-specific guidelines; for example, an OWNERS file under third_party/java_src must link to the corresponding OWNERS file in third_party/java. See an example here //piper/third_party/java_src/SAMPLE_JAVA_SRC_PACKAGE/OWNERS
  • The canonical list of FTE-equivalent groups is maintained in the linter code.

IMPORTANT: Under no circumstances may an OWNERS file under //third_party include the line set noparent.

BUILD file must declare the licensing type and export the license file

go/thirdparty/documentation#build
Lint warnings: go/thirdparty/linter#build

The BUILD file is required to have two rules: licenses() and exports_files(). The former declares the licensing type, while the latter identifies the file containing the license. The licensing type describes Google’s obligations in using the code. This is an example of the BUILD file for a project licensed under the “Apache 2.0” license:

# Foo, a framework for frobbing widgets.
package(default_visibility = ["//visibility:public"])

licenses(["notice"])

exports_files(["LICENSE"])

...other build rules (or perhaps none if you aren't using the build system)...

See details at go/thirdpartylicenses.

NOTE: Copyright notices are no longer required in Google-authored, internal-only files such as BUILD files. (go/copyright) On a related note, individual author information is now deprecated for //third_party package BUILD files. (go/copyright#author)

LICENSE must contain the text of the license for the code

go/thirdparty/documentation#license

NOTE: To be used at Google, third-party code must have some sort of license. If you have some agreement that you think gives you a right to use the code, and you aren’t sure if it counts as a license, send it to emailremoved@ and they will advise you.

Some packages only include the name of a “common” license (like “MIT” or “BSD”) in a README file somewhere, and not any actual license text. For the purposes of determining which license applies to the package, it is okay if the upstream package only links to the full text, rather than having the full text incorporated in a file. However, only including the name of the license in the LICENSE file instead of the complete license text is not good enough. There is a limited exception to this rule for R packages.

In either case, when the package is checked into //third_party, the contents of the LICENSE file must be the full text of the license, not a license name or a link to another file containing the full text. It must also be plain text. If you only have a PDF or other binary document, copy and paste the contents into a text file. (Please use a version that has already been word-wrapped to display nicely in Critique.)

The license for this code must be in a file named LICENSE in the root directory of the package. I.e., in the same directory as the METADATA file with a third_party field. If it was distributed like that, you’re good. If not, you need to create it. If there’s another file in the distribution with the license in it, rename it to LICENSE (e.g., rename LICENSE.txt or COPYING to LICENSE). If the license is only available in the comments or at a URL, extract and copy the text of the license into LICENSE.

If you are checking in commercially-licensed software, the text of the entire commercial agreement needs to be placed in the LICENSE file.

If there are multiple licenses for this code, put the text of all the licenses into LICENSE along with separators and comments as to the applications. For additional information about how to deal with multiple licenses see the multiple-licenses section of go/thirdpartylicenses.

The LICENSE file can be used to automatically generate “About” or “Legal” screens. Please wrap the LICENSE file to 80 characters and replace any non-ASCII characters with their ASCII equivalents so that such automated processes work well.

METADATA must contain a third_party field

go/thirdparty/documentation#metadata
Lint warnings: go/thirdparty/linter#metadata

The METADATA file contains information about where the code was retrieved from, what version it is, when it was last upgraded, security information, etc.. See go/thirdparty/metadata for a full treatise on the METADATA file.

NEXT: Get a review

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.