Rewrite/update //docs/adding_to_third_party.md.
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 <[email protected]>
Reviewed-by: Robbie Iannucci <[email protected]>
Reviewed-by: Chris Palmer <[email protected]>
Cr-Commit-Position: refs/heads/master@{#604750}diff --git a/docs/adding_to_third_party.md b/docs/adding_to_third_party.md
index 0d2e025..20f74561 100644
--- a/docs/adding_to_third_party.md
+++ b/docs/adding_to_third_party.md
@@ -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
@@ -51,72 +92,39 @@
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).
+[//third_party/libjpeg/LICENSE](../third_party/libjpeg/LICENSE).
-Run the following scripts:
-
-* `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
@@ -134,24 +142,10 @@
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}
