Skip to content

Commit

Permalink
Rewrite/update //docs/adding_to_third_party.md.
Browse files Browse the repository at this point in the history 
The page had gotten badly out of date. This CL rewrites most
of it to reflect current policy and practice and stops pointing
to viewvc for other links ;)

Change-Id: I62cc952a6f56954af723f4d57b2fadfd84227bda
Reviewed-on: https://chromium-review.googlesource.com/c/1298650
Commit-Queue: Dirk Pranke <dpranke@chromium.org>
Reviewed-by: Robbie Iannucci <iannucci@chromium.org>
Reviewed-by: Chris Palmer <palmer@chromium.org>
Cr-Commit-Position: refs/heads/master@{#604750}
  • Loading branch information
@dpranke
dpranke authored and Commit Bot committed Nov 1, 2018
1 parent 133f840 commit 568e95c
Showing 1 changed file with 82 additions and 88 deletions.
170 changes: 82 additions & 88 deletions docs/adding_to_third_party.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,33 +4,74 @@

Using third party code can save time and is consistent with our values - no need
to reinvent the wheel! We put all code that isn't written by Chromium developers
into src/third_party (even if you end up modifying just a few functions). We do
into `//third_party` (even if you end up modifying just a few functions). We do
this to make it easy to track license compliance, security patches, and supply
the right credit and attributions. It also makes it a lot easier for other
projects that embed our code to track what is Chromium licensed and what is
covered by other licenses.

## Get the Code
## Put the code in //third_party

When you find code you want to use, get it. This often means downloading: from
Sourceforge, from the hosting feature of Google Code, or from somewhere else.
Sometimes it can mean negotiating a license with another company and receiving
the code another way. Please describe the source in the README.chromium file,
described below. For security reasons, please retrieve the code as securely as
you can, using HTTPS and GPG signatures if available. If retrieving a tarball,
please do not check the tarball itself into the tree, but do list the source and
the SHA-512 hash (for verification) in the README.chromium and Change List. The
SHA-512 hash can be computed via the `shasum (sha512sum)` or `openssl`
utilities. If retrieving from a git repository, please list the SHA-512 hash.
By default, all code should be checked into [//third_party](../third_party/),
for the reasons given above. Other locations are only appropriate in a few
situations and need explicit approval; don't assume that because there's some
other directory with third_party in the name it's okay to put new things
there.

## Put the Code in (the right) third_party
## Get the code

By default, all code should be checked into
[src/third_party](http://src.chromium.org/viewvc/chrome/trunk/src/third_party/).
It is OK to have third_party subdirectories that are not top-level (e.g.
src/net/third_party), but don't add more third_party directories than necessary.
There are two common ways to depend on third-party code: you can reference a
Git repo directly (via entries in the DEPS file), or you can check in a
snapshot. The former is preferable if you are actively developing in it or need
access to the history; the latter is better if you don't need the full history
of the repo or don't need to pick up every single change. And, of course, if
the code you need isn't in a Git repo, you have to do the latter.

## Document the Code's Context
### Pulling the code via DEPS

If the code is in a Git repo that you want to mirror, please file an [infra git
ticket](https://bugs.chromium.org/p/chromium/issues/entry?template=Infra-Git)
to get the repo mirrored onto chromium.googlesource.com; we don't allow direct
dependencies on non-Google-hosted repositories, so that we can still build
if an external repository goes down..

Once the mirror is set up, add an entry to [//DEPS](../DEPS) so that gclient
will pull it in. If the code is only needed on some platforms, add a condition
to the deps entry so that developers on other platforms don't pull in things
they don't need.

As for specifying the path where the library is fetched, a path like
`//third_party/<project_name>/src` is highly recommended so that you can put
the file like OWNERS or README.chromium at `//third_party/<project_name>`. If
you have a wrong path in DEPS and want to change the path of the existing
library in DEPS, please ask the infrastructure team before committing the
change.

Lastly, add the new directory to Chromium's `//.gitignore`, so that it won't
show up as untracked files when you run `git status` on the main repository.

### Checking in the code directly

If you are checking in a snapshot, please describe the source in the
README.chromium file, described below. For security reasons, please retrieve
the code as securely as you can, using HTTPS and GPG signatures if available.
If retrieving a tarball, please do not check the tarball itself into the tree,
but do list the source and the SHA-512 hash (for verification) in the
README.chromium and Change List. The SHA-512 hash can be computed via
`sha512sum` or `openssl dgst -sha512`. If retrieving from a git
repository, please list the revision that the code was pulled from.

If you are checking the files in directly, you do not need an entry in DEPS
and do not need to modify `//.gitignore`.

### Checking in large files

_Accessible to Googlers only. Non-Googlers can email one of the people in
third_party/OWNERS for help.

See [Moving large files to Google Storage](https://goto.google.com/checking-in-large-files)

## Document the code's context

### Add OWNERS

Expand All @@ -51,72 +92,39 @@ As an OWNER, you're expected to:

You need a README.chromium file with information about the project from which
you're re-using code. See
[README.chromium.template](http://src.chromium.org/viewvc/chrome/trunk/src/third_party/README.chromium.template)
[//third_party/README.chromium.template](../third_party/README.chromium.template)
for a list of fields to include. A presubmit check will check this has the right
format.

README.chromium files contain a field indicating whether the package is
security-critical or not. A package is security-critical if it is compiled
into the product and does any of the following:

* Accepts untrustworthy inputs from the internet
* Parses or interprets complex input formats
* Sends data to internet servers
* Collects new data
* Influences or sets security-related policy (including the user experience)

### Add a LICENSE file and run related checks

You need a LICENSE file. Example:
[third_party/libjpeg/LICENSE](http://src.chromium.org/viewvc/chrome/trunk/src/third_party/libjpeg/LICENSE?revision=42288&view=markup).

Run the following scripts:
[//third_party/libjpeg/LICENSE](../third_party/libjpeg/LICENSE).

* `src/tools/licenses.py scan` - This will complain about incomplete or missing
data for third_party checkins. We use 'licenses.py credits' to generate the
about:credits page in Google Chrome builds.
Run `//tools/licenses.py scan`; this will complain about incomplete or missing
data for third_party checkins. We use `licenses.py credits` to generate the
about:credits page in Google Chrome builds.

If the library will never be shipped as a part of Chrome (e.g. build-time tools,
testing tools), make sure to set "License File" as "NOT_SHIPPED" so that the
license is not included in about:credits page ([more on this below](#credits)).

### Modify DEPS

If the code is applicable and will be compiled on all supported Chromium
platforms (Windows, Mac, Linux, Chrome OS, iOS, Android), check it in to
[src/third_party](http://src.chromium.org/viewvc/chrome/trunk/src/third_party/).

If the code is only applicable to certain platforms, check it in to
[src/third_party](http://src.chromium.org/viewvc/chrome/trunk/src/third_party/)
and add an entry to the
[DEPS](http://src.chromium.org/viewvc/chrome/trunk/src/DEPS) file that causes
the code to be checked out from src/third_party into src/third_party by gclient.

_Explanation: Checking it into src/third_party causes all developers to need to
check out your code. This wastes disk space cause syncing to take longer for
developers that don't need your code. When all platforms really do need the
code, checking it in to src/third_party allows some slight improvements over
DEPS._

As for specifying the path where the library is fetched, a path like
`src/third_party/<project_name>/src` is highly recommended so that you can put
the file like OWNERS or README.chromium at `third_party/<project_name>`. If you
have a wrong path in DEPS and want to change the path of the existing library in
DEPS, please ask the infrastructure team before committing the change.

### Checking in large files

_Accessible to Googlers only. Non-Googlers can email one of the people in
third_party/OWNERS for help._

See [Moving large files to Google Storage](https://goto.google.com/checking-in-large-files)

## Setting up ignore

If your code is synced via DEPS, you should add the new directory to Chromium's
`.gitignore`. This is necessary because Chromium's main git repository already
contains
[src/third_party](http://src.chromium.org/viewvc/chrome/trunk/src/third_party/)
and the project synced via DEPS is nested inside of it and its files regarded as
untracked. That is, anyone running `git status` from `src/` would see a clutter.
Your project's files are tracked by your repository, not Chromium's, so make
sure the directory is listed in Chromium's `.gitignore`.

## Get a Review
## Get a review

All third party additions and substantive changes like re-licensing need the
following sign-offs. Some of these are accessible to Googlers only. Non-Googlers
can email one of the people in third_party/OWNERS for help.
following sign-offs. Some of these are accessible to Googlers only.
Non-Googlers can email one of the people in
[//third_party/OWNERS](../third_party/OWNERS) for help.

* Get Chrome Eng Review approval. Googlers should see
go/chrome-eng-review. Please include information about the additional
Expand All @@ -134,24 +142,10 @@ can email one of the people in third_party/OWNERS for help.

Please send separate emails to the eng review and security lists.

Subsequent changes don't require third-party-owners approval; you can modify the
code as much as you want. When you update code, be mindful of security-related
mailing lists for the project and relevant CVE to update your package.

## Ask the infrastructure team to add a git mirror for the dependency

Before committing the DEPS, you need to ask the infra team to create a git
mirror for your dependency. [Create a
ticket](https://bugs.chromium.org/p/chromium/issues/entry?template=Infra-Git)
for infra and ask the infra team.

If you are using a git repo from googlesource.com then you must ensure that the
repository is configured to give the build bots unlimited quota, or else the
builders will fail to checkout with an "Over Quota" error. [Create a
ticket](https://bugs.chromium.org/p/chromium/issues/entry?template=Infra-Git)
for infra and ask the infra team what needs to be done. Note that you'll need
unlimited quota for at least two role accounts. See the quota status of
`boringssl` as an example.
Subsequent changes don't normally require third-party-owners or security
approval; you can modify the code as much as you want. When you update code, be
mindful of security-related mailing lists for the project and relevant CVE to
update your package.

## How we ensure that the right credits are displayed {#credits}

Expand Down

0 comments on commit 568e95c

Please sign in to comment.