Benedikt Meurer
69fc30e8b3
Going forward we want to have DevTools project documentation maintained within the source repository, following the model that Chromium uses for its project documentation[1]. This change sets up the basics for that, putting in place the main entry point (in docs/README.md) and moving the architecture documentation to the docs folders, as well as putting back the 3rd party guidelines here. We also adopt the simpler structure for images, making it easier to identify which document a given image file belongs to. [1]: https://chromium.googlesource.com/chromium/src/+/main/docs/README.md DISABLE_THIRD_PARTY_CHECK=reorganizing files Fixed: chromium:1358806 Change-Id: I70f7f90b95c7311ca24bede04ca9cdd5e4c31eaf Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/3865393 Commit-Queue: Kim-Anh Tran <kimanh@chromium.org> Reviewed-by: Yang Guo <yangguo@chromium.org> Reviewed-by: Kim-Anh Tran <kimanh@chromium.org> Auto-Submit: Benedikt Meurer <bmeurer@chromium.org>
3.8 KiB
Third-party Guidelines
[TOC]
When you want to integrate or use third-party content in DevTools, there are a couple of different ways to do so. Most of the time, we have to make a distinction between "third-party code we use as part of DevTools implementation" and "third-party code we use to build DevTools itself, but is not included in the product".
Third-party code included in DevTools bundle
All third-party content that you want to ship as part of the DevTools bundle
must be included in front_end/third_party. The typical way to update these
packages is to download the relevant packages from npm. Since DevTools does
not use a package.json to handle its dependencies (to make it possible to
review third-party changes by legal), most packages bundles are fetched with
wget.
For all these packages, the Chromium third-party guidelines apply.
Since DevTools ships as part of the Chrome binary, bundle size limitations apply. To make integration feasible, focus on small packages that (preferably) have no dependencies. This will make licensing checks feasible for Chromium reviewers and typically avoids inflating the bundle size.
Third-party tooling packages
For all third-party packages that are used either as part of the DevTools build
process or to augment engineers workflows (for example linters), we add them to
scripts/deps/manage_node_deps.py. This Python script has been approved by
Chromium licensing to be used, on the basis that it enforces all packages have a
license that is compatible with a set of pre-defined licensees.
If you want to use a new package as tooling process in engineer workflows, you
can add the package to the DEPS in the script and run npm run install-deps
to check in the new contents.
Only add new license types to LICENSES after you received approval
from opensource-licensing@google.com. Their response time is typically within
24 hours, so this typically is not a big hurdle.
To avoid excessive package updates, it is typically easiest to
update all packages in manage_node_deps.py once a month. Since NPM packages
can have a lot of (shared) transitive dependencies, updating the packages on a
specific day increases the chances that shared dependencies are deduplicated and
thus result in smaller repository sizes.
WARNING: Updating tools such as Rollup and TypeScript will cause all build cache output to be purged, as they are part of all DevTools modules. Whenever you are updating either of these tools, update these at the end of a working day to avoid full rebuilds for other engineers.
Chromium third-party DEPS
Some packages related to infrastructure are maintained by Chromium infra teams. These packages are typically uploaded to cloud storage buckets or are explicitly mirrored to a repository on https://chromium.googlesource.com. Examples include GN (Chromium/DevTools build system) or clang-format (multi-language formatter).
The packages in DEPS are typically kept automatically up-to-date with
autorollers. These autorollers will periodically update packages, which
engineers can fetch with running gclient sync.
These DEPS are checked out on all bots, which includes Chromium and
DevTools-specific bots. To avoid excessive network bandwidth usage, by default
do not check out packages if they are only used in specific situations.
Only include packages that are maintained by Chromium
infrastructure teams and are used to build DevTools in DEPS. For packages that
are DevTools-specific, prefer adding them to scripts/deps/manage_node_deps.py
instead.