opensource.google

Docs

Document the Code and its Context

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

In third_party, OWNERS files with non per-file rules should only exist within packages or directories designed to host multiple versions of a project. These should not be placed in organizational subdirectories.

The first line(s) in the OWNERS file must be:

  • Usernames of two full-time Googlers, OR
  • A file: directive pointing to another OWNERS file in //third_party

This provides a clear point-of-contact for anyone who needs to update the package or make changes to the package.

Owners tagged as cleanup-approver or approve-only satisfy the above requirement. Afterwards, additional owners may be listed as desired, including mdb groups.

The exceptions to this rule are:

  • 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.1

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

IMPORTANT: The requirements for BUILD files are changing soon. See here for details.

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)

Visibility

Internal sub-packages that should never be directly depended on are clear candidates for limited visibility.

You may also restrict visibility in order to limit your maintenance/support costs and to require people to ask for visibility. In most cases, specific visibility requests should be granted, but you may need to come to an agreement about the terms of such visibility. (i.e. shared ownership, turnaround on upgrade CLs, etc.)

IMPORTANT: by_exception_only licensed packages must have restricted visibility.

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.

IMPORTANT: LICENSE files must be files in Piper (symlinks are sometimes OK), not the output of a genrule. See bug …271 for details.

In all cases, 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.

Some upstream packages may not contain the actual license text in the upstream source. Instead, they may contain a clear indication that the entire package is licensed under a specific package. For example:

  • Include a clear phrase like “This is licensed under the MIT license” in a README.md file. (Only for common licenses.)
  • Only include a link to a LICENSE.
  • Include a SPDX identifier in an approved ecosystem standard metadata file (Node/npm: package.json, Rust: cargo.toml, R: DESCRIPTION)

In those cases, you must synthetically create a LICENSE file for import containing the text of the appropriate license based on the provided information. Include information in the CL description that you have done this. License text can generally be found on https://opensource.org/licenses.

(In cases where you’ve needed to create a synthetic license, you’re strongly encouraged to send pull requests upstream to add the full LICENSE text to the source repository.)

If you are checking in commercially-licensed software or other ‘by_exception_only’ licenses, those license terms need to be reviewed by license-escalation; see instructions for documenting commercial licenses.

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.

Google owned code

If the package being placed in third_party/ is composed only of first-party (i.e., Google owned) code, and has the (default) type PACKAGE, please use the following text in the LICENSE file.

Google owned, no external contributions.

Note that this does not apply to open source projects that have external contributors or intend to have external contributors.

A directory without (explicit or implicit) type: PACKAGE (for example, a directory with type GOOGLE_INTERNAL) should not contain a LICENSE file.

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

  1. http://linkremoved/

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.