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.
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 anotherOWNERS
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 underthird_party/java_src
must link to the correspondingOWNERS
file inthird_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
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
You are encouraged to use //visibility:public
where appropriate. Internal
sub-packages that should never be depended on are clear candidates for limited
visibility.
You may restrict visibility to specific packages 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 OK), not the
output of a genrule
. See bug …271 for details.
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.
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
- 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.