third_party packages shipped as part of the DevTools front_end/

This directory contains all packages that are shipped in the DevTools front_end/ bundle. All third_party packages that are solely used for building DevTools should live in //third_party instead. third_party packages included in this directory will be subject to additional security review and monitoring.

Inclusion of new front_end/third_party/ packages

If you would like to add a new third_party package to this directory, please perform the following steps:

1. Assess the increase in bundle size and make sure this is not too big. This will be determined on a case-by-case basis, taking into account the portion of DevTools users that will take advantage of the new feature.
   1. If you are unsure whether the size will be an issue, please email [email protected] for guidance before opening any CL.
2. Obtain security review from chrome. You can read full guidance on this process here.
   1. Send an email to [email protected] with some context, the package you want to add and a link to a Design Doc or other documentation
   2. Add devtools-dev+security@ in the CC and start the title with [DevTools].
   3. Note that all existing third_party packages in front_end/ will be legacied in, but will receive post-inclusion security review.
3. Open a single CL with only the source of the third_party package and required Ninja build configuration.
   1. Add [email protected] as a reviewer. The gwsq bot will choose an appropriate reviewer for the CL.
   2. All existing Chromium third_party policies about documenting the code‘s context still apply. You can read the "Document the code’s context" section here.
   3. You will be responsible for keeping the package up-to-date. As such, add yourself as OWNER.
   4. Wait for approval from both the securty- and the third-party reviewer before landing the CL. Reviewers might not have +1 permission so approval could be an email or a comment on the CL. See below for more information on updating existing packages.
4. After the first CL has been submitted, open a follow-up CL with the implementation/usage of the new third_party package.

Updating existing front_end/third_party/ packages

Packages must be updated on a suitable cadence (preferably monthly or weekly). Any breaking changes must be mitigated in a separate CL, before the package update CL is submitted. If breaking changes can not be mitigated in isolation, assess the overall impact on codebase and notify devtools-dev@ about the upcoming breaking change. That way, other code contributors are aware of potential merge conflicts and regression mitigations.

If the functionality of the package changed significantly in the update, you might have to obtain another security review. Ask devtools-dev+security@ for guidance if you are unsure.

How to fix Closure type-checking

Closure will try to type-check a third_party package as soon as it is imported by a DevTools module. This will fail should the third_party package not use JSDoc, or use it in way that is not supported by Closure. The workaround includes a couple of steps:

• For each file that is imported by DevTools and which Closure is unhappy about, we need to create a _types.js file along-side it. For example, if the package foo contains third_party/foo/package/foo.js, create a file third_party/foo/package/foo_types.js that exports the relevant types that Closure needs to know about.
• Add foo.js to the run_type_check.py script. This tells our build system to use foo_types.js instead of foo.js for type-checking.
• Don't forget to update the README.chromium of the third_party package to include the added _types.js files in the “Local Modifications” section.
• Any module.json that lists third_party/foo/package/foo.js in its modules section, needs to add the same file to the skip_compilation section.