chrome-devtools-frontend 1.0.1473514 → 1.0.1506453

package/docs/README.md

@@ -69,9 +69,9 @@ below.**
 
 Formats all code using clang-format.
 
-`npm run check`
+`npm test`
 
-Runs all static analysis checks on DevTools code.
+Runs all tests on DevTools code.
 
 
 ## Creating Documentation

package/docs/architecture_of_devtools.md

@@ -333,15 +333,15 @@ Now, the new panel is allowed to add a dependency edge on `models/workspace_diff
 
 # DevTools GRD integration
 
-To bundle DevTools with Chromium, DevTools builds its GRD file that will be consumed by [GRIT].
-The GRD file lists all required files that should be loaded either in Debug or Release mode.
-All files that should be bundled are listed in `config/gni/devtools_grd_files.gni`.
-If a file should be present in debug and release mode, add the file to `grd_files_release_sources`.
-If a file should only be present in debug mode, add the file to `grd_files_debug_sources`.
+To ship DevTools with Chromium, DevTools builds its GRD file that will be consumed by [GRIT].
+The GRD file lists all required files that should be loaded either in "bundled" or "unbundled" mode.
+All files that should be shipped are listed in `config/gni/devtools_grd_files.gni`.
+If a file should be present in "bundled" and "unbundled" mode, add the file to `grd_files_bundled_sources`.
+If a file should only be present in "unbundled" mode, add the file to `grd_files_unbundled_sources`.
 
 Note that `devtools_module` and `devtools_entrypoint` automatically take care of this for you.
-Any file included in `devtools_module` is only present in the Debug GRD file.
-Any file included as entrypoint of `devtools_entrypoint` is present in both the Release and Debug GRD file.
+Any file included in `devtools_module` is only present in the "unbundled" GRD file.
+Any file included as entrypoint of `devtools_entrypoint` is present in both the "bundled" and "unbundled" GRD file.
 
 There are additional actions that can add files to the GRD file, for example images or Markdown files.
 To allow for any action to define any relevant GRD file inclusions, DevTools uses [GN `metadata` definitions].
@@ -376,7 +376,7 @@ node_action("generate_css_vars") {
 ```
 
 The GN metadata is traversed in `/BUILD.gn` and is written to a JSON file in `:input_grd_files`.
-The JSON file is compared to the contents of `:expected_grd_files` which takes the `grd_files_release_sources` and `grd_files_debug_sources` (only in Debug mode) files as input.
+The JSON file is compared to the contents of `:expected_grd_files` which takes the `grd_files_bundled_sources` and `grd_files_unbundled_sources` (only in "unbundled" mode) files as input.
 
 If the collected input files matches the expected listed GRD files, the GRD files is written to a GRD file by `:generate_devtools_grd`.
 The GRD file is placed in `gen/third_party/devtools-frontend/src/front_end/` in Chromium.

package/docs/committers_policy.md

@@ -29,6 +29,8 @@ Once you get approval from the existing committers, you'll be added to [chrome-d
 
 In the most unfavorable circumstances, the process could extend up to two weeks. Maintain your commitment to writing patches. Even in the uncommon instances where a nomination fails, the objection is frequently something specific to resolve, such as "more patches" or "not enough people are familiar with this person's work."
 
+Two-factor authentication is a requirement for adding your account as a committer. If you haven't done so already, you'll need to set up a security key on your account.
+
 # **Maintaining committer status**
 
 Maintaining committer status in the DevTools project is straightforward. Continue to contribute and help the project in meaningful ways. If you remain inactive for 12 consecutive months (absence of comments, uploads, and reviews), you will be notified via email about removal in 7 days and then automatically removed from the list. You may reapply for committer status without going through the full nomination process.

package/docs/contributing/README.md

@@ -5,11 +5,13 @@
 This page assumes a working Chromium DevTools [checkout and build](../get_the_code.md).
 
 1.   [Quick Start](#Quick-Start)
-2.   [Design Documents](./design.md)
-3.   [Contributing changes](./changes.md)
-4.   [Issues Guidelines](./issues.md)
-5.   [Settings, Experiments, and Features](./settings-experiments-features.md)
-5.   [Legal Stuff](#Legal-Stuff)
+2.   [IDE Setup](#IDE-Setup)
+3.   [Design Documents](./design.md)
+4.   [Contributing changes](./changes.md)
+5.   [Issues Guidelines](./issues.md)
+6.   [Settings, Experiments, and Features](./settings-experiments-features.md)
+7.   [Infrastructure](./infrastructure.md)
+8.   [Legal Stuff](#Legal-Stuff)
 
 
 ## Quick Start
@@ -295,6 +297,28 @@ button. This will start a final run of tests and land it after a green run.
     *   `git cl web` will open that URL in your browser.
 
 
+## IDE Setup
+
+### VS Code
+
+When using the standalone checkout, we already provide out of the box setup for
+Visual Studio Code, so most things will work out of the box. Below are a few
+steps that you should still check regardless (especially when you're not using
+the standalone checkout).
+
+#### Select the correct TypeScript version
+
+Open any `.ts` file in your VS code, hit Ctrl+Shift+P (on Windows/Linux) or
+Cmd+Shift+P (on macOS), and choose **TypeScript: Select TypeScript Version...**
+from the command palette. In the drop down select **Use Workspace Version**.
+
+![](./images/quickstart-vscode-tsversion.png "Select TypeScript Version")
+
+This will ensure that you have proper type definitions, even when the VS Code
+installation doesn't provide them (for whatever reason). And it also ensures
+that type definitions are consistent between what is used during the build and
+what is used within your IDE.
+
 ## Legal stuff
 
 All contributors must have valid Gerrit/Google accounts (which means you must

package/docs/contributing/changes.md

@@ -138,7 +138,7 @@ Step-by-step guide on how to merge:
 1. The cherry-pick CL is created
    ([example](https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/1928913)).
 1. Get it reviewed if necessary.
-1. Once merge request approval is granted (see step 1), click the hamburger menu on the cherry-pick CL and select “Submit”. (Setting the Commit-Queue bit (+2) has no effect because these branches don’t have a commit queue.)
+1. Once merge request approval, set Commit-Queue bit (+2) and wait for the CL to land. (Branches have a commit queue too)
 1. Done.
 
 ### Merge conflicts

package/docs/contributing/infrastructure.md

@@ -0,0 +1,89 @@
+# Infrastructure
+
+Chromium DevTools has an infrastructure component that consists of
+recipes that define how to build and test the frontend in CQ and CI
+plus a set of rollers to automate dependency updates.
+
+## Overview of the code
+
+The configuration for the DevTools infrastructure is in the
+[`infra/config`](https://chromium.googlesource.com/devtools/devtools-frontend/+/refs/heads/infra/config)
+branch. The recipes are located in the
+[`chromium/tools/build`](https://chromium.googlesource.com/chromium/tools/build/+/refs/heads/main)
+repository.
+
+[Luci-config app](https://config.luci.app) is consuming the configuration from infra/config. You can force refresh from the app. DevTools configuration is located [here](https://chrome-internal.googlesource.com/infradata/config/+/master/configs/luci-config/projects.cfg).
+
+## Checking out the infra config branch
+
+```bash
+mkdir devtools-infra
+cd devtools-infra
+fetch devtools-frontend
+cd devtools-frontend
+git checkout infra/config
+```
+
+Run `git clean -fd` and remove the rest of the remaining files from the `main`
+branch.
+
+## Submitting an infra config change
+
+First, create a branch for the change and set upstream to the `infra/config`:
+
+```bash
+git new-branch branch-name --upstream_current
+```
+
+- `buckets/try.star`: configurations for default try-jobs for a CL.
+- `buckets/try-misc.star`: configurations for additional builders that
+  can be manually added to CLs in Gerrit or via `git cl try`.
+- `buckets/cpp_debugging_extension.star`: configurations for the C++
+  debugging extension tests.
+- `buckets/serving_app.star`: configurations for the DevTools server
+  app.
+- `buckets/ci.star`: configurations to run on the main branch after a CL
+  is submitted also known as CI or Waterfall builders.
+- `buckets/ci-hp.star`: configurations for the highly privileged
+builders that rolls dependencies.
+
+After you update a `.star` file, re-generate generated files using
+`lucicfg main.star`.
+
+These `.star` definitions roughly correspond to the CI console view
+https://ci.chromium.org/ui/p/devtools-frontend.
+
+Run `git cl upload`. Infra changes are submitted similar to the regular
+frontend CLs using `git cl upload`. After a review on Gerrit, the change
+will be merged into the infra branch.
+
+Note that the changes made in the CL are not picked up by the bots before the
+change is merged. After the CL is merged, the change will be deployed to the
+bots.
+
+## Submitting a recipe change
+
+Follow the instructions at
+https://chromium.googlesource.com/chromium/tools/build/+/refs/heads/main/recipes/README.md
+and upload a CL for
+[`chromium/tools/build`](https://chromium.googlesource.com/chromium/tools/build/+/refs/heads/main).
+
+## Updating test commands in the infrastructure
+
+The DevTools recipes are defined in
+[`chromium/tools/build`](https://chromium.googlesource.com/chromium/tools/build/+/refs/heads/main)
+repository. Once a change is made there, the recipes are packaged
+as a cipd package and the `infra/config` data defines how to fetch that
+cipd package. The recipes are bundled by
+https://ci.chromium.org/ui/p/chrome/builders/official.infra/recipe-bundler.
+
+DevTools recipes live at
+https://chromium.googlesource.com/chromium/tools/build/+/refs/heads/main/recipes/recipes/devtools/.
+
+## Determining if a change needs to run tests
+
+The
+[`try.star`](https://chromium.googlesource.com/devtools/devtools-frontend/+/refs/heads/infra/config/buckets/try.star)
+file in the `infra/config` branch contains the logic that determines
+which builders are needed to verify a CQ. See `custom_locationsfilters`
+for the current logic.

package/docs/cookbook/localization.md

@@ -21,19 +21,21 @@ import * as i18n from '../i18n/i18n.js';
 // at the top of example.js file, after import statements
 const UIStrings = {
   /**
-    * @description A string that is already added
-    */
-  alreadyAddedString: 'Someone already created a "UIStrings = {}" and added this string',
+   * @description A string that is already added
+   */
+  alreadyAddedString:
+    'Someone already created a "UIStrings = {}" and added this string',
   /**
-    * @description This is an example description for my new string
-    */
+   * @description This is an example description for my new string
+   */
   addThisString: 'The new string I want to add',
   /**
-    * @description This is an example description for my new string with placeholder
-    * @example {example for placeholder} PH1
-    */
+   * @description This is an example description for my new
+   * string with placeholder
+   * @example {example for placeholder} PH1
+   */
   addAnotherString: 'Another new string I want to add, with {PH1}',
-};
+} as const;
 const str_ = i18n.i18n.registerUIStrings('example.js', UIStrings);
 const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_);
 
@@ -44,39 +46,44 @@ const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_);
 const message1 = i18nString(UIStrings.addThisString);
 console.log(message1); // The new string I want to add
 
-const message2 = i18nString(UIStrings.addAnotherString, {PH1: 'a placeholder'});
-console.log(message2); // Another new string I want to add, with a placeholder
+const message2 = i18nString(UIStrings.addAnotherString, {
+  PH1: 'a placeholder',
+});
+// Another new string I want to add, with a placeholder
+console.log(message2);
 ```
 
 1.  If there is already `UIStrings = {}` declared in the file, add your string
     to it. If there isn't `UIStrings = {}` in the file, create one and add your
     string, also register the new UIStrings into the `en-US.json` by adding:
 
-    1.  `const str_ = i18n.i18n.registerUIStrings({the current fileName.js,
-        relative to front_end}, UIStrings);`
-    1.  `const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_);`
+    ```js
+    // Filename should be relative to front_end folder
+    const str_ = i18n.i18n.registerUIStrings('<filename>', UIStrings);
+    const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_);
+    ```
 
-2.  Add description and examples for placeholder(if any):
+2.  Add description and examples for placeholder (if any):
 
-    1.  To specify the description, use `@description …` `@description This is
-        an example description for my new string`
-    2.  To specify an example for placeholder, use `@example {…} …` `@example
-        {example for placeholder} PH1`
+    1.  To specify the description, use `@description …` `@description This is an example description for my new string`
+    2.  To specify an example for placeholder, use `@example {…} …` `@example {example for placeholder} PH1`
     3.  To distinguish messages with the same content, use `@meaning …`
-        `@meaning This is an example meaning to differentiate this message from
-        the other message with same content`
+        `@meaning This is an example meaning to differentiate this message from the other message with same content`
 
 3.  Make sure your string is localizable:
 
-    1.  Do not assume word order by using concatenation. Use the whole string. ❌
-        `javascript 'Add' + 'breakpoint'` ✔️ `javascript 'Add breakpoint'` or ❌
-        `javascript let description = 'first part' if (condition) description +=
-        ' second part'` ✔️ `javascript let description if (condition)
-        description = 'first part second part' else description = 'first part'`
+    1.  Do not assume word order by using concatenation. Use the whole string.
+
+    - ❌ `javascript 'Add' + 'breakpoint'`
+    - ✔️ `javascript 'Add breakpoint'` or
+    - ❌ `javascript let description = 'first part' if (condition) description +=' second part'`
+    - ✔️ `javascript let description if (condition) description = 'first part second part' else description = 'first part'`
+
     2.  Use placeholder over concatenation. This is so that the translators can
         adjust variable order based on what works in another language. For
-        example: ❌ `javascript 'Check ' + title + ' for more information.'` ✔️
-        `javascript 'Check {PH1} for more information.', {PH1: title}`
+        example:
+        - ❌ `javascript 'Check ' + title + ' for more information.'`
+        - ✔️ `javascript 'Check {PH1} for more information.', {PH1: title}`
     3.  If your string contains <b>leading or trailing white space</b>, it's
         usually an indication that it's half of a sentence. This decreases
         localizability as it's essentially concatenating. Modify it so that it
@@ -88,38 +95,35 @@ console.log(message2); // Another new string I want to add, with a placeholder
 
         ❌ Not localized
 
-        -   Numbers: 1, 1.23, 1.2e3, etc.
-        -   Application data: error codes, enums, database names, rgba, urls,
-            etc.
+        - Numbers: 1, 1.23, 1.2e3, etc.
+        - Application data: error codes, enums, database names, rgba, urls,
+          etc.
 
         ✔️ Can be localized
 
-        -   Words and sentences
-        -   Punctuation
-        -   Units of measurement: kb/s, mph, etc.
+        - Words and sentences
+        - Punctuation
+        - Units of measurement: kb/s, mph, etc.
 
 4.  The following commands would add the new strings to `en-US.json`:
 
-    -   `git cl presubmit --upload`, or
-    -   `node third_party/i18n/collect-strings.js` under the DevTools src folder
+    - `git cl presubmit --upload`, or
+    - `node third_party/i18n/collect-strings.js` under the DevTools src folder
 
 5.  Strings containing possible plurals have a special format in ICU. This is
     because plurals work quite differently in other languages, e.g. special
     forms for two or three items.
 
-    ❌ `javascript if (count === 1) { str = '1 breakpoint'; } else { str = '{n}
-    breakpoints', {n: count}; }`
+    ❌ `javascript if (count === 1) { str = '1 breakpoint'; } else { str = '{n} breakpoints', {n: count}; }`
 
-    ✔️ `javascript '{n, plural, =1 {# breakpoint} other {# breakpoints}}', {n:
-    count};`
+    ✔️ `javascript '{n, plural, =1 {# breakpoint} other {# breakpoints}}', {n:count};`
 
-    -   '#' is replaced with the value of `n`
-    -   'n' is a naming convention, but any name can be used
-    -   Nesting placeholders inside of plurals is allowed
-    -   Put the entire string within the plural switch, e.g. `{# breakpoints
-        were found}`, not `{# breakpoints} were found`
-    -   Always provide the `=1` and the `other` case, even if they are the same
-        for English.
+    - `#` is replaced with the value of `n`
+    - `n` is a naming convention, but any name can be used
+    - Nesting placeholders inside of plurals is allowed
+    - Put the entire string within the plural switch, e.g. `{# breakpoints were found}`, not `{# breakpoints} were found`
+    - Always provide the `=1` and the `other` case, even if they are the same
+      for English.
 
 ### Modifying a string
 
@@ -146,14 +150,17 @@ object for placeholders (if any)
 
 const UIStrings = {
   /**
-    * @description This is an example description for my new string with placeholder
-    * @example {example for placeholder} PH1
-    * @example {example 2 for placeholder 2} PH2
-    */
+   * @description This is an example description for my new string with placeholder
+   * @example {example for placeholder} PH1
+   * @example {example 2 for placeholder 2} PH2
+   */
   addAnotherString: 'Another new string I want to add, with {PH1} and {PH2}',
-};
+} as const;
 
-message = i18nString(UIStrings.addAnotherString, {PH1: 'a placeholder', PH2: 'another placeholder'});
+message = i18nString(UIStrings.addAnotherString, {
+  PH1: 'a placeholder',
+  PH2: 'another placeholder',
+});
 ```
 
 ### i18nLazyString
@@ -221,7 +228,7 @@ This call is a named cast. Use it in places where a localized string is expected
 but the term you want to use does not require translation. Instead of locking
 the whole phrase or using a placeholder-only phrase, use `lockedString`.
 
-```javascript
+```js
 someFunctionRequiringALocalizedString(i18n.i18n.lockedString('HTTP'));
 ```
 
@@ -239,7 +246,7 @@ const UIStrings = {
    * @description Tooltip text that appears when hovering over the 'Focusable' attribute name under the Computed Properties section in the Accessibility pane of the Elements pane.
    */
   computedPropertyTooltip: 'If true, this element can receive focus.',
-};
+} as const;
 ```
 
 **Bad description**:
@@ -250,39 +257,39 @@ const UIStrings = {
    * @description Elements pane 'Focusable' tooltip.
    */
   computedPropertyTooltip: 'If true, this element can receive focus.',
-};
+} as const;
 ```
 
 ### What information should I provide in the message description?
 
--   The type of UI element where the text is displayed. Is it regular text, a
-    label, button text, a tooltip, a link, or an accessible label? Button text
-    is often imperative i.e. a command to do something, which is important to
-    know in some languages.
--   *When*: What triggers the string and/or what is the result? What page or
-    text comes before and after? e.g. "Status text while waiting for X", "Shown
-    when the audit is finished and X error was encountered".
--   What do the placeholders stand for? Placeholder examples are sent to
-    translators, but extra information in the description will help too. e.g.
-    "Total time in ms that the profile took to complete", "The CSS property name
-    that is being edited"
--   Is this a verb or a noun? Many words in English can be both, e.g. 'request',
-    'address', 'change', 'display', 'increase'. Particularly if the string is
-    short, this can be hard to guess. If it's an adjective, what does it refer
-    to? This is important for inflection in some languages, where the ending of
-    the adjective must change for gender or case.
--   Explain or name any complex terms, e.g. "Trust Tokens are a web API -
-    https://web.dev/trust-tokens/"
--   Where is the text located? e.g. A table header in the Sources panel, a
-    context-menu item in the Network panel. Many strings in the code base have
-    *only* the location, which is not the most important context.
+- The type of UI element where the text is displayed. Is it regular text, a
+  label, button text, a tooltip, a link, or an accessible label? Button text
+  is often imperative i.e. a command to do something, which is important to
+  know in some languages.
+- _When_: What triggers the string and/or what is the result? What page or
+  text comes before and after? e.g. "Status text while waiting for X", "Shown
+  when the audit is finished and X error was encountered".
+- What do the placeholders stand for? Placeholder examples are sent to
+  translators, but extra information in the description will help too. e.g.
+  "Total time in ms that the profile took to complete", "The CSS property name
+  that is being edited"
+- Is this a verb or a noun? Many words in English can be both, e.g. 'request',
+  'address', 'change', 'display', 'increase'. Particularly if the string is
+  short, this can be hard to guess. If it's an adjective, what does it refer
+  to? This is important for inflection in some languages, where the ending of
+  the adjective must change for gender or case.
+- Explain or name any complex terms, e.g. "Trust Tokens are a web API -
+  https://web.dev/trust-tokens/"
+- Where is the text located? e.g. A table header in the Sources panel, a
+  context-menu item in the Network panel. Many strings in the code base have
+  _only_ the location, which is not the most important context.
 
 ## How to prevent a term being localized
 
 Any text within the backticks will not be translated. For example, if the
 'robots.txt' in string 'Requesting for robots.txt …' should not be translated:
 
-```javascript
+```js
 // in example.js file
 
 import * as i18n from '../i18n/i18n.js';
@@ -291,7 +298,7 @@ const UIStrings = {
    * @description Example description. Note: "robots.txt" is a canonical filename and should not be translated.
    */
   requestMessage: 'Requesting for `robots.txt` …',
-};
+} as const;
 const str_ = i18n.i18n.registerUIStrings('example.js', UIStrings);
 
 const message = i18nString(UIStrings.requestMessage);

package/docs/get_the_code.md

@@ -46,19 +46,19 @@ it'll automatically create and initialize it.
 You can disable type checking (via TypeScript) by using the `devtools_skip_typecheck`
 argument in your GN configuration. This uses [esbuild](https://esbuild.github.io/)
 instead of `tsc` to compile the TypeScript files and generally results in much
-shorter build times. To switch the `Default` target to esbuild, use
+shorter build times.
 
-```bash
-gn gen out/Default --args="devtools_skip_typecheck=true"
-```
-
-or if you don't want to change the default target, use something like
+Additionally, we now bundle files together by default in all builds, which has
+a build time cost. If you want an even fast fast build, you might want to opt
+out of bundling by setting `devtools_bundle` to `false`
 
 ```bash
-gn gen out/fast-build --args="devtools_skip_typecheck=true"
+gn gen out/fast-build --args="devtools_skip_typecheck=true devtools_bundle=false"
 ```
 
-and use `npm run build -- -t fast-build` to build this target.
+and use `npm run build -- -t fast-build` to build this target (you can of course
+also just change the `Default` target to skip bundling and type checking).
+
 
 ### Rebuilding automatically
 
@@ -193,7 +193,7 @@ npm start -- -u
 Just like with Chrome itself, you can also control the set of enabled and disabled features using
 
 ```bash
-npm start -- --enable-features=DevToolsAutomaticFileSystems
+npm start -- --enable-features=DevToolsWellKnown
 npm start -- --disable-features=DevToolsWellKnown --enable-features=DevToolsFreestyler:multimodal/true
 ```