diff --git a/.eslintignore b/.eslintignore deleted file mode 100644 index fa1a075cf180..000000000000 --- a/.eslintignore +++ /dev/null @@ -1,36 +0,0 @@ -front_end/.eslintrc.js -front_end/diff/diff_match_patch.jD -front_end/models/javascript_metadata/NativeFunctions.js -front_end/models/javascript_metadata/DOMPinnedProperties.ts - -// All of the scripts in this folder are auto-generated so don't lint them. -front_end/generated/ - -// Any third_party addition has its source code checked out into -// third_party/X/package, so we ignore that code as it's not code we author or -// own. -front_end/third_party/*/package/ -// Any JS files are also not authored by devtools-frontend, so we ignore those. -front_end/third_party/**/*.js -// Lighthouse doesn't have a package/ folder but has other nested folders, so -// we ignore any folders within the lighthouse directory. -front_end/third_party/lighthouse/*/ -// The CodeMirror bundle file is auto-generated and rolled-up as part of the -// install script, so we don't need to lint it. -front_end/third_party/codemirror.next/bundle.ts -// Lit lib files are auto-generated and rolled up as part of the install script. -front_end/third_party/lit/src/*.ts -// @puppeteer/replay is auto-generated. -front_end/third_party/puppeteer-replay/**/*.ts - -extensions/cxx_debugging/third_party/ - -node_modules -scripts/migration/**/*.js -scripts/protocol_typescript/*.js -scripts/deps/tests/fixtures -test/**/fixtures/ -test/e2e/**/*.js -test/shared/**/*.js - -*.d.ts diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 59d87dbd9d5d..000000000000 --- a/.eslintrc.js +++ /dev/null @@ -1,275 +0,0 @@ -// Copyright 2020 The Chromium Authors. All rights reserved. -// Use of this source code is governed by a BSD-style license that can be -// found in the LICENSE file. - -// clang-format off - -const path = require('path'); -const rulesDirPlugin = require('eslint-plugin-rulesdir'); -rulesDirPlugin.RULES_DIR = path.join(__dirname, 'scripts', 'eslint_rules', 'lib'); - -module.exports = { - 'root': true, - - 'env': {'browser': true, 'es6': true}, - - 'parser': '@typescript-eslint/parser', - - 'plugins': [ - '@typescript-eslint', - 'mocha', - 'rulesdir', - 'import', - 'jsdoc', - ], - - 'parserOptions': {'ecmaVersion': 9, 'sourceType': 'module'}, - - /** - * ESLint rules - * - * All available rules: http://eslint.org/docs/rules/ - */ - 'rules': { - /** - * Enforced rules - */ - - // syntax preferences - 'quotes': ['error', 'single', {'avoidEscape': true, 'allowTemplateLiterals': false}], - 'semi': 'error', - 'no-extra-semi': 'error', - 'comma-style': ['error', 'last'], - 'wrap-iife': ['error', 'inside'], - 'spaced-comment': ['error', 'always', {'markers': ['*']}], - 'eqeqeq': 'error', - 'accessor-pairs': ['error', {'getWithoutSet': false, 'setWithoutGet': false}], - 'curly': 'error', - 'new-parens': 'error', - 'func-call-spacing': 'error', - 'arrow-parens': ['error', 'as-needed'], - 'eol-last': 'error', - - // anti-patterns - 'no-caller': 'error', - 'no-case-declarations': 'error', - 'no-cond-assign': 'error', - 'no-console': ['error', {'allow': ['assert', 'context', 'error', 'timeStamp', 'time', 'timeEnd', 'warn']}], - 'no-debugger': 'error', - 'no-dupe-keys': 'error', - 'no-duplicate-case': 'error', - 'no-else-return': ['error', {'allowElseIf': false}], - 'no-empty-character-class': 'error', - 'no-global-assign': 'error', - 'no-implied-eval': 'error', - 'no-labels': 'error', - 'no-multi-str': 'error', - 'no-new-object': 'error', - 'no-octal-escape': 'error', - 'no-self-compare': 'error', - 'no-shadow-restricted-names': 'error', - 'no-unreachable': 'error', - 'no-unsafe-negation': 'error', - 'no-unused-vars': ['error', {'args': 'none', 'vars': 'local'}], - 'no-var': 'error', - 'no-with': 'error', - 'prefer-const': 'error', - 'radix': 'error', - 'valid-typeof': 'error', - 'no-return-assign': ['error', 'always'], - 'no-implicit-coercion': 'error', - - // es2015 features - 'require-yield': 'error', - 'template-curly-spacing': ['error', 'never'], - - // file whitespace - 'no-multiple-empty-lines': ['error', {'max': 1}], - 'no-mixed-spaces-and-tabs': 'error', - 'no-trailing-spaces': 'error', - 'linebreak-style': ['error', 'unix'], - - /** - * Disabled, aspirational rules - */ - - 'indent': ['off', 2, {'SwitchCase': 1, 'CallExpression': {'arguments': 2}, 'MemberExpression': 2}], - - // brace-style is disabled, as eslint cannot enforce 1tbs as default, but allman for functions - 'brace-style': ['off', 'allman', {'allowSingleLine': true}], - - // key-spacing is disabled, as some objects use value-aligned spacing, some not. - 'key-spacing': ['off', {'beforeColon': false, 'afterColon': true, 'align': 'value'}], - // quote-props is diabled, as property quoting styles are too varied to enforce. - 'quote-props': ['off', 'as-needed'], - - // no-implicit-globals will prevent accidental globals - 'no-implicit-globals': 'off', - 'no-unused-private-class-members': 'error', - - // forbids interfaces starting with an I prefix. - '@typescript-eslint/naming-convention': - ['error', {'selector': 'interface', 'format': ['PascalCase'], 'custom': {'regex': '^I[A-Z]', 'match': false}}], - '@typescript-eslint/explicit-member-accessibility': 'off', - '@typescript-eslint/no-explicit-any': [ - "error", - { - "ignoreRestArgs": true - } - ], - - // Closure does not properly typecheck default exports - 'import/no-default-export': 'error', - - /** - * Catch duplicate import paths. For example this would catch the following example: - * import {Foo} from './foo.js' - * import * as FooModule from './foo.js' - **/ - 'import/no-duplicates': 'error', - - // Try to spot '// console.log()' left over from debugging - 'rulesdir/commented_out_console': 'error', - - // Prevent imports being commented out rather than deleted. - 'rulesdir/commented_out_import': 'error', - - // DevTools specific rules - 'rulesdir/es_modules_import': 'error', - 'rulesdir/check_license_header': 'error', - /** - * Ensures that JS Doc comments are properly aligned - all the starting - * `*` are in the right place. - */ - 'jsdoc/check-alignment': 'error', - }, - 'overrides': [{ - 'files': ['*.ts'], - 'parserOptions': { - 'allowAutomaticSingleRunInference': true, - 'project': path.join(__dirname, 'config', 'typescript', 'tsconfig.eslint.json'), - }, - 'rules': { - '@typescript-eslint/explicit-member-accessibility': ['error', {'accessibility': 'no-public'}], - 'comma-dangle': 'off', - '@typescript-eslint/comma-dangle': ['error', 'always-multiline'], - - // run just the TypeScript unused-vars rule, else we get duplicate errors - 'no-unused-vars': 'off', - '@typescript-eslint/no-unused-vars': ['error', {'argsIgnorePattern': '^_'}], - // run just the TypeScript semi rule, else we get duplicate errors - 'semi': 'off', - '@typescript-eslint/semi': 'error', - '@typescript-eslint/member-delimiter-style': [ - 'error', { - 'multiline': {'delimiter': 'semi', 'requireLast': true}, - 'singleline': {'delimiter': 'comma', 'requireLast': false}, - 'overrides': { - 'interface': { - 'singleline': {'delimiter': 'semi', 'requireLast': false}, - 'multiline': {'delimiter': 'semi', 'requireLast': true} - }, - 'typeLiteral': { - 'singleline': {'delimiter': 'comma', 'requireLast': false}, - 'multiline': {'delimiter': 'comma', 'requireLast': true} - } - } - } - ], - '@typescript-eslint/no-floating-promises': ['error', {ignoreVoid: true}], - // func-call-spacing doesn't work well with .ts - 'func-call-spacing': 'off', - '@typescript-eslint/func-call-spacing': 'error', - - /** - * Enforce that enum members are explicitly defined: - * const enum Foo { A = 'a' } rather than const enum Foo { A } - */ - '@typescript-eslint/prefer-enum-initializers': 'error', - /** - * Ban non-null assertion operator, e.g.: - * this.foo!.toLowerCase() - */ - '@typescript-eslint/no-non-null-assertion': 'error', - '@typescript-eslint/consistent-type-imports': 'error', - 'rulesdir/no_underscored_properties': 'error', - 'rulesdir/prefer_readonly_keyword': 'error', - 'rulesdir/inline_type_imports': 'error', - } - }, { - 'files': ['*.test.ts', 'test/**/*.ts', '**/testing/*.ts'], - 'rules': { - // errors on it('test') with no body - 'mocha/no-pending-tests' : 'error', - - // errors on {describe, it}.only - 'mocha/no-exclusive-tests' : 'error', - - 'mocha/no-async-describe': 'error', - 'mocha/no-global-tests': 'error', - 'mocha/no-nested-tests': 'error', - - 'rulesdir/check_test_definitions' : 'error', - 'rulesdir/avoid_assert_equal' : 'error', - 'rulesdir/no_repeated_tests' : 'error', - 'rulesdir/compare_arrays_with_assert_deepequal' : 'error', - 'rulesdir/ban_screenshot_test_outside_perf_panel' : 'error', - 'rulesdir/trace_engine_test_timeouts' : 'error', - '@typescript-eslint/naming-convention' : - [ - 'error', - { - 'selector' : - [ - 'function', 'accessor', 'method', 'property', - 'parameterProperty' - ], - 'format' : ['camelCase'], - }, - { - // Allow PascalCase as well as it is used for dynamic module imports. - 'selector' : 'variable', - 'format' : ['camelCase', 'PascalCase', 'UPPER_CASE'], - }, - { - 'selector' : 'classProperty', - 'modifiers' : ['static', 'readonly'], - 'format' : ['UPPER_CASE'], - }, - { - 'selector' : 'enumMember', - 'format' : ['PascalCase', 'UPPER_CASE'], - }, - { - 'selector' : ['typeLike'], - 'format' : ['PascalCase'], - }, - { - // Also allow UPPER_CASE so argument function to evaluate can take constants as arguments without renaming. - 'selector' : 'parameter', - 'format' : ['camelCase', 'UPPER_CASE'], - 'leadingUnderscore' : 'allow', - }, - { - // Object literals may be constructed as arguments to external libraries which follow different styles. - 'selector' : ['objectLiteralMethod', 'objectLiteralProperty'], - 'modifiers' : ['public'], - 'format' : null, - }, - ], - '@typescript-eslint/no-non-null-assertion' : 'off', - }, - 'settings': { - 'mocha/additionalCustomNames': [ - { 'name': 'describeWithDevtoolsExtension', 'type': 'suite', 'interfaces': [ 'BDD', 'TDD' ] }, - { 'name': 'describeWithEnvironment', 'type': 'suite', 'interfaces': [ 'BDD', 'TDD' ] }, - { 'name': 'describeWithLocale', 'type': 'suite', 'interfaces': [ 'BDD', 'TDD' ] }, - { 'name': 'describeWithMockConnection', 'type': 'suite', 'interfaces': [ 'BDD', 'TDD' ] }, - { 'name': 'describeWithRealConnection', 'type': 'suite', 'interfaces': [ 'BDD', 'TDD' ] }, - { 'name': 'itScreenshot', 'type': 'testCase', 'interfaces': [ 'BDD', 'TDD' ] }, - ] - } - }], -}; - -// clang-format on diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs index c94ea38ee11d..cfb88573bc9d 100644 --- a/.git-blame-ignore-revs +++ b/.git-blame-ignore-revs @@ -349,3 +349,11 @@ aaf6c64ae8d791f878599bf2cea8a9b1e6a5001c # Always add braces to single-line if-statements (https://crrev.com/c/1821526) 1d6e57a0e314d709029cac52b98898b828f45a12 + +# [AI Assistance] Renames and refactorings (https://crrev.com/c/6080811) +786bd4290956c5b8560a03cf73d860572559e382 + +# RPP mass-renames. https://crrev.com/c/5867685 https://crrev.com/c/6191870 https://crrev.com/c/6190947 +8da83d7f627b0588b1c49d7761a90368efbfed73 +b1b834b0a1f9e61213fba85d8bc4a3c9ccfdefd7 +a59de5d27b5977b0bb8d260634f1d8d45e69cfdf \ No newline at end of file diff --git a/.gitallowed b/.gitallowed index 7b8e5490652c..783898c50d77 100644 --- a/.gitallowed +++ b/.gitallowed @@ -1,4 +1,6 @@ # This key is expected to be visible in the frontend code # b/349721878 CRUX_API_KEY +# Publicly-visible API key for Firebase analytics, used in NetworkRequestHandler.test.ts +AIzaSyCGxLbbFQxH4BV1fY0RODlxTos9nJa2l_g diff --git a/.gitattributes b/.gitattributes index 88b415de08f1..452030b1bf46 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,3 +1,4 @@ package-lock.json binary +front_end/ui/visual_logging/KnownContextValues.ts merge=union # Automatically normalize line endings (to LF) for all text-based files. -* text=auto eol=lf \ No newline at end of file +* text=auto eol=lf diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 9f7472e85b16..7f16b3bbd9b1 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -5,7 +5,7 @@ on: jobs: build: - runs-on: ubuntu-latest + runs-on: ubuntu-22.04 steps: - uses: actions/checkout@v3 with: diff --git a/.gitignore b/.gitignore index 665a098796dc..47fe3c66a67d 100644 --- a/.gitignore +++ b/.gitignore @@ -24,8 +24,9 @@ config.gypi /interactions-coverage /perf-data npm-debug.log -/scripts/javascript_natives/node_modules /scripts/protocol_typescript/*.js +/scripts/ai_assistance/data +/scripts/ai_assistance/performance-trace-downloads /build /buildtools @@ -52,3 +53,8 @@ test/perf/.generated /.gclient_entries /.gclient_previous_sync_commits /.cipd + +# Linters caches +.eslintcache +.stylelintcache +**/tsconfig.tsbuildinfo diff --git a/.stylelintrc.json b/.stylelintrc.json index cc32ef6650c3..a7bee3d4449e 100644 --- a/.stylelintrc.json +++ b/.stylelintrc.json @@ -1,8 +1,6 @@ { "extends": "stylelint-config-standard", - "plugins": [ - "./scripts/stylelint_rules/lib/use_theme_colors.js" - ], + "plugins": ["./scripts/stylelint_rules/lib/use_theme_colors.mjs"], "rules": { "plugin/use_theme_colors": true, "alpha-value-notation": "percentage", @@ -11,21 +9,20 @@ "comment-empty-line-before": null, "declaration-no-important": true, "color-named": "never", - "max-empty-lines": 1, "selector-type-no-unknown": [ true, { - "ignoreTypes": [ - "/^devtools-/" - ] + "ignoreTypes": ["/^devtools-/", "/^dt-/", "x-link"] } ], - "max-line-length": null, "selector-class-pattern": null, "keyframes-name-pattern": null, "selector-no-vendor-prefix": null, "property-no-vendor-prefix": null, "value-no-vendor-prefix": null, - "media-feature-name-no-vendor-prefix": null - } + "media-feature-name-no-vendor-prefix": null, + "no-descending-specificity": null + }, + "reportNeedlessDisables": true, + "reportUnscopedDisables": true } diff --git a/.vscode/devtools-workspace-launch.json b/.vscode/devtools-workspace-launch.json index 7b99c3de47ec..b58ec5cd25e2 100644 --- a/.vscode/devtools-workspace-launch.json +++ b/.vscode/devtools-workspace-launch.json @@ -2,16 +2,12 @@ "version": "0.2.0", "configurations": [ { - "type": "pwa-chrome", + "type": "chrome", "request": "launch", "name": "Run unit tests in VS Code debugger", "preLaunchTask": "1-build_Debug", - "runtimeExecutable": "/usr/bin/npm", - "runtimeArgs": [ - "run", - "test", - "front_end" - ], + "runtimeExecutable": "npm", + "runtimeArgs": ["run", "test", "front_end"], "port": 7722, "timeout": 30000, "browserLaunchLocation": "workspace", @@ -19,43 +15,29 @@ "trace": true }, { - "type": "pwa-node", + "type": "node", "request": "launch", "name": "Run end-to-end tests in VS Code debugger", "preLaunchTask": "1-build_Debug", - "runtimeExecutable": "/usr/bin/npm", - "runtimeArgs": [ - "run", - "test", - "test/e2e" - ] + "runtimeExecutable": "npm", + "runtimeArgs": ["run", "test", "test/e2e"] }, { - "type": "pwa-node", + "type": "node", "request": "launch", "name": "Run test", "cwd": "${workspaceFolder}", - "runtimeExecutable": "/usr/bin/npm", - "runtimeArgs": [ - "run", - "test", - "--", - "${file}" - ] + "runtimeExecutable": "npm", + "runtimeArgs": ["run", "test", "--", "${file}"] }, { - "type": "pwa-node", + "type": "node", "request": "launch", "name": "Debug test", "cwd": "${workspaceFolder}", - "runtimeExecutable": "/usr/bin/npm", - "runtimeArgs": [ - "run", - "test", - "--", - "--debug", - "${file}" - ] + "runtimeExecutable": "npm", + "console": "integratedTerminal", + "runtimeArgs": ["run", "test", "--", "--debug", "${file}"] } ] } diff --git a/.vscode/devtools-workspace-settings.json b/.vscode/devtools-workspace-settings.json index 7866da22310a..e3b424d4fc9a 100644 --- a/.vscode/devtools-workspace-settings.json +++ b/.vscode/devtools-workspace-settings.json @@ -1,9 +1,7 @@ { - "eslint.runtime": "third_party/node/node.py", + "eslint.runtime": "$PATHED by scripts/deps/sync-vscode-settings.mjs", "typescript.tsdk": "node_modules/typescript/lib", "debug.javascript.terminalOptions": { - "skipFiles": [ - "node_modules/typescript/**" - ] + "skipFiles": ["node_modules/typescript/**"] } } diff --git a/.vscode/devtools-workspace-tasks.json b/.vscode/devtools-workspace-tasks.json index b10d49d389f1..22251905df14 100644 --- a/.vscode/devtools-workspace-tasks.json +++ b/.vscode/devtools-workspace-tasks.json @@ -6,7 +6,7 @@ "label": "1-build_Debug", "type": "shell", "command": "npm run build", - "group": {"kind": "build", "isDefault": true}, + "group": { "kind": "build", "isDefault": true }, "presentation": { "echo": true, "reveal": "always" @@ -14,12 +14,13 @@ "problemMatcher": [ { "owner": "typescript", - "fileLocation": ["relative", "${workspaceRoot}/out/Default"], + "fileLocation": ["relative", "${workspaceRoot}"], "pattern": { - "regexp": "^([^\\s].*)\\((\\d+,\\d+)\\):\\s*(.*)$", + "regexp": "^([^\\s].*)\\((\\d+,\\d+)\\): error (TS\\d+):\\s*(.*)$", "file": 1, "location": 2, - "message": 3 + "code": 3, + "message": 4 } } ] diff --git a/.vscode/extensions.json b/.vscode/extensions.json index 6442ab314300..628e082841d2 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -1,7 +1,3 @@ { - "recommendations": [ - "dbaeumer.vscode-eslint", - "bierner.lit-html", - "npclaudiu.vscode-gn" - ] -} \ No newline at end of file + "recommendations": ["dbaeumer.vscode-eslint", "runem.lit-plugin", "Google.gn"] +} diff --git a/AUTHORS b/AUTHORS index 123e0a1a2b7e..4d5c2a1aa08c 100644 --- a/AUTHORS +++ b/AUTHORS @@ -11,7 +11,9 @@ # Please keep the list sorted. # BEGIN individuals section. +AbdAlRahman Gad Ajay Panthagani +Alesandro Ortiz Alexander Stammbach Alexey Rodionov Ankit Mishra @@ -21,6 +23,7 @@ Axel Chong Biboswan Roy Boris Verkhovskiy Carl Espe +Casey Primozic Charles Vazac Conner Turner Daniel bellfield @@ -42,8 +45,9 @@ Jacky Hu Jake Mulhern Jan Keitel Jeffrey Chen -Jesper van den Ende Jerome Vouillon +Jesper van den Ende +Jithil p Ponnan Juba Borgohain Julian Geppert Junseo Yoo @@ -69,10 +73,14 @@ Rajasekar Murugan Ross Wollman Royi Hagigi Ryan Puhalovich +Satvic Dhawan Sebastian Markbåge Serg Kryvonos +Sergio Avalos Simon Siefke Stephen Tsoi-A-Sue +Sunnylost +TaegeonKim Thomas Stokes Tony Kostowny Toshiaki Tanaka @@ -89,6 +97,7 @@ Yuan Zhuang # END individuals section. # BEGIN organizations section. +Bloomberg Finance L.P. <*@bloomberg.net> Cloudflare, Inc. <*@cloudflare.com> Facebook, Inc. <*@fb.com> Google Inc. <*@google.com> @@ -101,3 +110,4 @@ The Chromium Authors <*@chromium.org> The Qt Company <*@qt.io> # Please DO NOT APPEND here. See comments at the top of the file. # END organizations section. + diff --git a/BUILD.gn b/BUILD.gn index 0fda66bec31f..134c536ac143 100644 --- a/BUILD.gn +++ b/BUILD.gn @@ -5,14 +5,16 @@ import("./config/gni/devtools_grd_files.gni") import("./config/gni/devtools_image_files.gni") import("./front_end/emulated_devices/optimized/optimized_images.gni") +import("./scripts/build/ninja/copy.gni") import("./scripts/build/ninja/node.gni") import("./scripts/build/ninja/vars.gni") +import("./scripts/build/typescript/typescript.gni") import("./third_party/blink/public/public_features.gni") -import("./third_party/typescript/typescript.gni") #------------------------------------------------------------------------------- devtools_frontend_resources_deps = [ + ":favicon", "front_end", "test", ] @@ -199,3 +201,7 @@ ts_library("frontend_indexer_tsconfig") { sourceslist = "$root_build_dir/indexer_ts_files.txt" public_deps = [ ":indexer_ts_files" ] } + +copy_to_gen("favicon") { + sources = [ "favicon.ico" ] +} diff --git a/DEPS b/DEPS index d1d0dba1cef9..50cd92acc94e 100644 --- a/DEPS +++ b/DEPS @@ -12,27 +12,27 @@ vars = { 'build_with_chromium': False, 'build_url': 'https://chromium.googlesource.com/chromium/src/build.git', - 'build_revision': '7a8285c06acd753e6228263f48e5595e20ca1577', + 'build_revision': 'e13953ced04ed05f45aa3c961bd6d802aced74ec', 'buildtools_url': 'https://chromium.googlesource.com/chromium/src/buildtools.git', - 'buildtools_revision': '3ef44a2b92d5dd1faa5189a06f3a5febe6db2d58', + 'buildtools_revision': '6f359296daa889aa726f3d05046b9f37be241169', 'depot_tools_url': 'https://chromium.googlesource.com/chromium/tools/depot_tools.git', - 'depot_tools_revision': 'cba7859885743d3c9865e4f1c076a6f2b698932d', + 'depot_tools_revision': 'f40ddcd8d51626fb7be3ab3c418b3f3be801623f', 'inspector_protocol_url': 'https://chromium.googlesource.com/deps/inspector_protocol', - 'inspector_protocol_revision': '2915acabcf62efd7257c57bb8a443a7c389c65cb', + 'inspector_protocol_revision': '940abfc668be2591483f7132145593c6a047f3cf', # Keeping track of the last time we rollerd the browser protocol files. - 'chromium_browser_protocol_revision' : 'a51d9c64b04a596df7ca3a57a88d5427746fcda2', + 'chromium_browser_protocol_revision' : '43e4a99fb37358d50c74187b7944a4519683b8a7', 'clang_format_url': 'https://chromium.googlesource.com/external/github.com/llvm/llvm-project/clang/tools/clang-format.git', - 'clang_format_revision': '3c0acd2d4e73dd911309d9e970ba09d58bf23a62', + 'clang_format_revision': '37f6e68a107df43b7d7e044fd36a13cbae3413f2', 'emscripten_tag': 'ade9d780ff17c88d81aa13860361743e3c1e1396', # GN CIPD package version. - 'gn_version': 'git_revision:b2afae122eeb6ce09c52d63f67dc53fc517dbdc8', + 'gn_version': 'git_revision:6e8e0d6d4a151ab2ed9b4a35366e630c55888444', 'cmake_version': 'version:2@3.21.3', @@ -43,13 +43,13 @@ vars = { 'lldb_eval_revision': 'e87123a7e639bf1d86f24c37079570fb7fa00b72', # ninja CIPD package version. - # https://chrome-infra-packages.appspot.com/p/infra/3pp/build_support/ninja-1_11_1/ - 'ninja_version': 'version:2@1.11.1.chromium.2', + # https://chrome-infra-packages.appspot.com/p/infra/3pp/tools/ninja + 'ninja_version': 'version:3@1.12.1.chromium.4', # Chrome version used for tests. It should be regularly updated to # match the Canary version listed here: # https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions.json - 'chrome': '128.0.6611.0', + 'chrome': '136.0.7101.0', # 'magic' text to tell depot_tools that git submodules should be accepted but # but parity with DEPS file is expected. @@ -57,11 +57,20 @@ vars = { # condition to allowlist deps for non-git-source processing. 'non_git_source': 'True', + + # siso CIPD package version + 'siso_version': 'git_revision:68bdc49e4e23aef066fc652cbdb1b4973aab1a31', } # Only these hosts are allowed for dependencies in this DEPS file. # If you need to add a new host, contact chrome infrastracture team. -allowed_hosts = [ 'chromium.googlesource.com', 'chrome-infra-packages.appspot.com' ] +allowed_hosts = [ + 'chromium.googlesource.com', + 'chrome-infra-packages.appspot.com', + + # TODO(b/337061377): Move into a separate alllowed gcs bucket list. + 'chromium-nodejs', +] deps = { 'third_party/clang-format/script': { @@ -125,7 +134,7 @@ deps = { 'packages': [ { 'package': 'infra/3pp/tools/esbuild/${{platform}}', - 'version': 'version:2@0.14.13.chromium.2', + 'version': 'version:3@0.25.1.chromium.2', } ], 'dep_type': 'cipd', @@ -136,6 +145,16 @@ deps = { 'url': Var('build_url') + '@' + Var('build_revision'), 'condition': 'build_with_chromium == False', }, + 'third_party/siso': { + 'packages': [ + { + 'package': 'infra/build/siso/${{platform}}', + 'version': Var('siso_version'), + } + ], + 'dep_type': 'cipd', + 'condition': 'not build_with_chromium and host_cpu != "s390" and host_os != "zos" and host_cpu != "ppc"', + }, 'third_party/depot_tools': { 'url': Var('depot_tools_url') + '@' + Var('depot_tools_revision'), 'condition': 'build_with_chromium == False', @@ -147,69 +166,73 @@ deps = { 'third_party/ninja': { 'packages': [ { - 'package': 'infra/3pp/build_support/ninja-1_11_1/${{platform}}', + 'package': 'infra/3pp/tools/ninja/${{platform}}', 'version': Var('ninja_version'), } ], 'dep_type': 'cipd', 'condition': 'build_with_chromium == False', }, -} - -hooks = [ # Pull down Node binaries for WebUI toolchain. - { - 'name': 'node_linux64', - 'pattern': '.', - 'condition': 'host_os == "linux" and build_with_chromium == False', - 'action': [ 'python3', - 'third_party/depot_tools/download_from_google_storage.py', - '--no_resume', - '--extract', - '--no_auth', - '--bucket', 'chromium-nodejs/20.11.0', - '-s', 'third_party/node/linux/node-linux-x64.tar.gz.sha1', + 'third_party/node/linux': { + 'dep_type': 'gcs', + 'condition': 'host_os == "linux" and build_with_chromium == False and non_git_source', + 'bucket': 'chromium-nodejs', + 'objects': [ + { + 'object_name': 'fa98c6432de572206bc5519f85e9c96bd518b039', + 'sha256sum': 'fb563633b5bfe2d4307075c54c6bb54664a3b5ec6bc811f5b15742720549007a', + 'size_bytes': 50288755, + 'generation': 1730835522207929, + 'output_file': 'node-linux-x64.tar.gz', + }, ], }, - { - 'name': 'node_mac', - 'pattern': '.', - 'condition': 'host_os == "mac" and build_with_chromium == False and host_cpu != "arm64"', - 'action': [ 'python3', - 'third_party/depot_tools/download_from_google_storage.py', - '--no_resume', - '--extract', - '--no_auth', - '--bucket', 'chromium-nodejs/20.11.0', - '-s', 'third_party/node/mac/node-darwin-x64.tar.gz.sha1', - ], + 'third_party/node/mac': { + 'dep_type': 'gcs', + 'condition': 'host_os == "mac" and build_with_chromium == False and host_cpu != "arm64" and non_git_source', + 'bucket': 'chromium-nodejs', + 'objects': [ + { + 'object_name': '4c8952a65a1ce7a2e4cff6db68f9b7454c46349f', + 'sha256sum': 'fadb4530fbe6e35ed298848c66102a0aa7d92974789e6222c4eadee26a381e7e', + 'size_bytes': 45672893, + 'generation': 1730835514382259, + 'output_file': 'node-darwin-x64.tar.gz', + }, + ], }, - { - 'name': 'node_mac', - 'pattern': '.', - 'condition': 'host_os == "mac" and build_with_chromium == False and host_cpu == "arm64"', - 'action': [ 'python3', - 'third_party/depot_tools/download_from_google_storage.py', - '--no_resume', - '--extract', - '--no_auth', - '--bucket', 'chromium-nodejs/20.11.0', - '-s', 'third_party/node/mac/node-darwin-arm64.tar.gz.sha1', - ], + 'third_party/node/mac_arm64': { + 'dep_type': 'gcs', + 'condition': 'host_os == "mac" and build_with_chromium == False and host_cpu == "arm64" and non_git_source', + 'bucket': 'chromium-nodejs', + 'objects': [ + { + 'object_name': '0886aa6a146cb5c213cb09b59ed1075982e4cb57', + 'sha256sum': 'd39e2d44d58bb89740b9aca1073959fc92edbdbbe810a5e48448e331cf72c196', + 'size_bytes': 44929037, + 'generation': 1730835518292126, + 'output_file': 'node-darwin-arm64.tar.gz', + }, + ], }, - { - 'name': 'node_win', - 'pattern': '.', - 'condition': 'host_os == "win" and build_with_chromium == False', - 'action': [ 'python3', - 'third_party/depot_tools/download_from_google_storage.py', - '--no_resume', - '--no_auth', - '--bucket', 'chromium-nodejs/20.11.0', - '-s', 'third_party/node/win/node.exe.sha1', - ], + 'third_party/node/win': { + 'dep_type': 'gcs', + 'condition': 'host_os == "win" and build_with_chromium == False and non_git_source', + 'bucket': 'chromium-nodejs', + 'objects': [ + { + 'object_name': '907d7e104e7389dc74cec7d32527c1db704b7f96', + 'sha256sum': '7447c4ece014aa41fb2ff866c993c708e5a8213a00913cc2ac5049ea3ffc230d', + 'size_bytes': 80511640, + 'generation': 1730835526374028, + 'output_file': 'node.exe', + }, + ], }, +} +hooks = [ { # Ensure that the DEPS'd "depot_tools" has its self-update capability # disabled. @@ -217,7 +240,7 @@ hooks = [ 'pattern': '.', 'condition': 'build_with_chromium == False', 'action': [ - 'python3', + 'vpython3', 'third_party/depot_tools/update_depot_tools_toggle.py', '--disable', ], @@ -228,7 +251,7 @@ hooks = [ 'name': 'download_chrome_win', 'pattern': '.', 'condition': 'host_os == "win" and build_with_chromium == False', - 'action': [ 'python3', + 'action': [ 'vpython3', 'scripts/deps/download_chrome.py', '--url=https://storage.googleapis.com/chrome-for-testing-public/' + Var('chrome') + '/win64/chrome-win64.zip', '--target=third_party/chrome', @@ -242,7 +265,7 @@ hooks = [ 'name': 'download_chrome_mac', 'pattern': '.', 'condition': 'host_os == "mac" and build_with_chromium == False and host_cpu != "arm64"', - 'action': [ 'python3', + 'action': [ 'vpython3', 'scripts/deps/download_chrome.py', '--url=https://storage.googleapis.com/chrome-for-testing-public/' + Var('chrome') + '/mac-x64/chrome-mac-x64.zip', '--target=third_party/chrome', @@ -256,7 +279,7 @@ hooks = [ 'name': 'download_chrome_mac', 'pattern': '.', 'condition': 'host_os == "mac" and build_with_chromium == False and host_cpu == "arm64"', - 'action': [ 'python3', + 'action': [ 'vpython3', 'scripts/deps/download_chrome.py', '--url=https://storage.googleapis.com/chrome-for-testing-public/' + Var('chrome') + '/mac-arm64/chrome-mac-arm64.zip', '--target=third_party/chrome', @@ -270,7 +293,7 @@ hooks = [ 'name': 'download_chrome_linux', 'pattern': '.', 'condition': 'host_os == "linux" and build_with_chromium == False', - 'action': [ 'python3', + 'action': [ 'vpython3', 'scripts/deps/download_chrome.py', '--url=https://storage.googleapis.com/chrome-for-testing-public/' + Var('chrome') + '/linux64/chrome-linux64.zip', '--target=third_party/chrome', @@ -280,26 +303,42 @@ hooks = [ '--version_number=' + Var('chrome'), ], }, - { # Update LASTCHANGE for build script timestamps 'name': 'lastchange', 'condition': 'build_with_chromium == False', 'pattern': '.', - 'action': ['python3', 'build/util/lastchange.py', + 'action': ['vpython3', 'build/util/lastchange.py', '-o', 'build/util/LASTCHANGE'], }, { 'name': 'emscripten', 'pattern': '.', 'condition': 'build_with_chromium == False', - 'action': ['python3', 'scripts/deps/download_emscripten.py', Var('emscripten_tag'), 'third_party/emscripten-releases'], + 'action': ['vpython3', 'scripts/deps/download_emscripten.py', Var('emscripten_tag'), 'third_party/emscripten-releases'], }, { 'name': 'VS Code settings', 'pattern': '.', 'condition': 'build_with_chromium == False', - 'action': ['python3', 'third_party/node/node.py', '--output', 'scripts/deps/sync-vscode-settings.js'] + 'action': [ + 'vpython3', + 'third_party/node/node.py', + '--output', + # Silence the "Importing JSON modules" warning + '--no-warnings=ExperimentalWarning', + 'scripts/deps/sync-vscode-settings.mjs' + ] + }, + { + 'name': 'configure_siso', + 'pattern': '.', + 'condition': 'build_with_chromium == False', + 'action': ['python3', + 'build/config/siso/configure_siso.py', + '--rbe_instance', + 'projects/rbe-chrome-untrusted/instances/default_instance', + ], }, ] diff --git a/PRESUBMIT.py b/PRESUBMIT.py index cf6e869a126a..17f1c9d980a0 100644 --- a/PRESUBMIT.py +++ b/PRESUBMIT.py @@ -28,6 +28,9 @@ """ DevTools presubmit script +See http://goo.gle/devtools-testing-guide#Presubmit-checks for more how to +run presubmit checks in DevTools. + See http://dev.chromium.org/developers/how-tos/depottools/presubmit-scripts for more details about the presubmit API built into gcl. """ @@ -67,6 +70,21 @@ def _ExecuteSubProcess(input_api, output_api, script_path, args, results): return results +def _IsEnvCog(input_api): + old_sys_path = sys.path[:] + devtools_root = input_api.PresubmitLocalPath() + depot_tools = input_api.os_path.join(devtools_root, 'third_party', + 'depot_tools') + try: + sys.path.append(depot_tools) + from gclient_utils import IsEnvCog + if IsEnvCog(): + return True + finally: + sys.path = old_sys_path + return False + + def _CheckBugAssociation(input_api, output_api, is_committing): results = [output_api.PresubmitNotifyResult('Bug Association Check:')] bugs = input_api.change.BugsFromDescription() @@ -127,61 +145,17 @@ def _CheckESBuildVersion(input_api, output_api): return results -def _CheckEnumeratedHistograms(input_api, output_api): - enumerated_histograms_files = [ - input_api.os_path.join(input_api.PresubmitLocalPath(), 'front_end', - 'devtools_compatibility.js'), - input_api.os_path.join(input_api.PresubmitLocalPath(), 'front_end', - 'core', 'host', 'InspectorFrontendHostAPI.ts') - ] - affected_main_files = _getAffectedFiles(input_api, - enumerated_histograms_files, [], - ['.js', '.ts']) - if len(affected_main_files) == 0: +def _CheckFormat(input_api, output_api): + if _IsEnvCog(input_api): return [ - output_api.PresubmitNotifyResult( - 'No affected files for UMA Enumerated Histograms check') + output_api.PresubmitPromptWarning( + 'Non-git environment detected, skipping _CheckFormat.') ] - results = [ - output_api.PresubmitNotifyResult( - 'Running UMA Enumerated Histograms check:') - ] - script_path = input_api.os_path.join(input_api.PresubmitLocalPath(), - 'scripts', - 'check_enumerated_histograms.js') - results.extend(_checkWithNodeScript(input_api, output_api, script_path)) - return results - - -def _CheckFormat(input_api, output_api): - files_with_potential_large_diffs = _getAffectedFiles( - input_api, [ - input_api.os_path.join(input_api.PresubmitLocalPath(), - 'node_modules'), - input_api.os_path.join(input_api.PresubmitLocalPath(), 'front_end', - 'third_party'), - input_api.os_path.join(input_api.PresubmitLocalPath(), 'front_end', - 'generated'), - input_api.os_path.join(input_api.PresubmitLocalPath(), 'front_end', - 'models', 'javascript_metadata'), - ], [], []) - - # Changes to the above directories can produce large diffs. This is a problem on Windows, - # where clang-format-diff.py specifies all the diff ranges on the command line when invoking - # clang-format. Since command line length is limited on Win, the invocation fails. - # As a heuristic, we'll format all touched files fully if we suspect that the diff could - # be large. - # TODO(crbug.com/1068198): Remove once `git cl format --js` can handle large CLs. - additional_args = [] - if (len(files_with_potential_large_diffs) > 0): - additional_args = ['--full'] - results = [output_api.PresubmitNotifyResult('Running Format Checks:')] return _ExecuteSubProcess(input_api, output_api, - ['git', 'cl', 'format', '--js'] + - additional_args, [], results) + ['git', 'cl', 'format', '--js'], [], results) def _CheckDevToolsRunESLintTests(input_api, output_api): @@ -199,16 +173,22 @@ def _CheckDevToolsRunESLintTests(input_api, output_api): sys.path = original_sys_path eslint_rules_dir_path = input_api.os_path.join( input_api.PresubmitLocalPath(), 'scripts', 'eslint_rules') - eslint_rules_affected_files = _getAffectedFiles(input_api, - [eslint_rules_dir_path], - [], []) + eslint_rules_checked_paths = [ + # Check if EsLint is updated + input_api.os_path.join(input_api.PresubmitLocalPath(), 'node_modules', + 'eslint'), + # Check for rules changes + eslint_rules_dir_path, + ] + eslint_rules_affected_files = _getAffectedFiles( + input_api, eslint_rules_checked_paths, [], []) if (len(eslint_rules_affected_files) == 0): return [] mocha_path = devtools_paths.mocha_path() eslint_tests_path = input_api.os_path.join(eslint_rules_dir_path, 'tests', - '*_test.js') + '*.test.js') results = [output_api.PresubmitNotifyResult('ESLint rules unit tests')] results.extend( @@ -219,6 +199,54 @@ def _CheckDevToolsRunESLintTests(input_api, output_api): return results +def _CheckDevToolsRunStylelintTests(input_api, output_api): + # Check for changes in the stylelint_rules directory, and run the stylelint rules + # tests if so. + # We don't do this on every CL as most do not touch the rules, but if we do + # change them we need to make sure all the tests are passing. + original_sys_path = sys.path + try: + sys.path = sys.path + [ + input_api.os_path.join(input_api.PresubmitLocalPath(), 'scripts') + ] + import devtools_paths + finally: + sys.path = original_sys_path + + stylelint_tests_path = input_api.os_path.join( + input_api.PresubmitLocalPath(), 'scripts', 'stylelint_rules') + stylelint_rules_check_paths = [ + input_api.os_path.join(input_api.PresubmitLocalPath(), 'node_modules', + 'stylelint'), + # Rule is added/updated + stylelint_tests_path, + # Variable declaration used in test are changed + input_api.os_path.join(input_api.PresubmitLocalPath(), 'front_end', + 'application_tokens.css'), + input_api.os_path.join(input_api.PresubmitLocalPath(), 'front_end', + 'design_system_tokens.css'), + input_api.os_path.join(input_api.PresubmitLocalPath(), 'front_end', + 'inspectorCommon.css'), + ] + stylelint_rules_affected_files = _getAffectedFiles( + input_api, stylelint_rules_check_paths, [], []) + + if (len(stylelint_rules_affected_files) == 0): + return [] + + mocha_path = devtools_paths.mocha_path() + stylelint_tests_path = input_api.os_path.join(stylelint_tests_path, + 'tests', '*.test.js') + + results = [output_api.PresubmitNotifyResult('Stylelint rules unit tests')] + results.extend( + # The dot reporter is more concise which is useful to not get LOADS of + # output when just one test fails. + _checkWithNodeScript(input_api, output_api, mocha_path, + ['--reporter', 'dot', stylelint_tests_path])) + return results + + def _CheckDevToolsRunBuildTests(input_api, output_api): # Check for changes in the build/tests directory, and run the tests if so. # We don't do this on every CL as most do not touch the rules, but if we do @@ -253,17 +281,14 @@ def _CheckDevToolsRunBuildTests(input_api, output_api): return results -def _CheckDevToolsStyleJS(input_api, output_api): - results = [output_api.PresubmitNotifyResult('JS style check:')] +def _CheckDevToolsLint(input_api, output_api): + results = [output_api.PresubmitNotifyResult('Lint Check:')] lint_path = input_api.os_path.join(input_api.PresubmitLocalPath(), - 'scripts', 'test', - 'run_lint_check_js.mjs') + 'scripts', 'test', 'run_lint_check.mjs') front_end_directory = input_api.os_path.join( input_api.PresubmitLocalPath(), 'front_end') - component_docs_directory = input_api.os_path.join(front_end_directory, - 'ui', 'components', - 'docs') + inspector_overlay_directory = input_api.os_path.join( input_api.PresubmitLocalPath(), 'inspector_overlay') test_directory = input_api.os_path.join(input_api.PresubmitLocalPath(), @@ -272,35 +297,39 @@ def _CheckDevToolsStyleJS(input_api, output_api): 'scripts') default_linted_directories = [ - front_end_directory, test_directory, scripts_directory, - inspector_overlay_directory + front_end_directory, + test_directory, + scripts_directory, + inspector_overlay_directory, ] - eslint_related_files = [ + lint_related_files = [ input_api.os_path.join(input_api.PresubmitLocalPath(), 'node_modules', 'eslint'), + input_api.os_path.join(input_api.PresubmitLocalPath(), 'node_modules', + 'stylelint'), input_api.os_path.join(input_api.PresubmitLocalPath(), 'node_modules', '@typescript-eslint'), - input_api.os_path.join(input_api.PresubmitLocalPath(), '.eslintrc.js'), input_api.os_path.join(input_api.PresubmitLocalPath(), - '.eslintignore'), - input_api.os_path.join(front_end_directory, '.eslintrc.js'), - input_api.os_path.join(component_docs_directory, '.eslintrc.js'), - input_api.os_path.join(test_directory, '.eslintrc.js'), - input_api.os_path.join(scripts_directory, 'test', - 'run_lint_check_js.py'), - input_api.os_path.join(scripts_directory, 'test', - 'run_lint_check_js.mjs'), - input_api.os_path.join(scripts_directory, '.eslintrc.js'), + 'eslint.config.mjs'), input_api.os_path.join(scripts_directory, 'eslint_rules'), + input_api.os_path.join(input_api.PresubmitLocalPath(), + '.stylelintrc.json'), + input_api.os_path.join(input_api.PresubmitLocalPath(), + '.stylelintignore'), + # This file includes the LitAnalyzer rules + input_api.os_path.join(input_api.PresubmitLocalPath(), + 'tsconfig.json'), + input_api.os_path.join(scripts_directory, 'test', + 'run_lint_check.mjs'), ] - lint_config_files = _getAffectedFiles(input_api, eslint_related_files, [], - ['.js', '.py', '.eslintignore']) + lint_config_files = _getAffectedFiles(input_api, lint_related_files, [], + ['.js', '.py']) should_bail_out, files_to_lint = _getFilesToLint( input_api, output_api, lint_config_files, default_linted_directories, - ['.js', '.ts'], results) + ['.css', '.mjs', '.js', '.ts'], results) if should_bail_out: return results @@ -314,55 +343,6 @@ def _CheckDevToolsStyleJS(input_api, output_api): return results -def _CheckDevToolsStyleCSS(input_api, output_api): - results = [output_api.PresubmitNotifyResult('CSS style check:')] - lint_path = input_api.os_path.join(input_api.PresubmitLocalPath(), - 'scripts', 'test', - 'run_lint_check_css.js') - - front_end_directory = input_api.os_path.join( - input_api.PresubmitLocalPath(), 'front_end') - inspector_overlay_directory = input_api.os_path.join( - input_api.PresubmitLocalPath(), 'inspector_overlay') - default_linted_directories = [ - front_end_directory, inspector_overlay_directory - ] - - scripts_directory = input_api.os_path.join(input_api.PresubmitLocalPath(), - 'scripts') - - stylelint_related_files = [ - input_api.os_path.join(input_api.PresubmitLocalPath(), 'node_modules', - 'stylelint'), - input_api.os_path.join(input_api.PresubmitLocalPath(), - '.stylelintrc.json'), - input_api.os_path.join(input_api.PresubmitLocalPath(), - '.stylelintignore'), - input_api.os_path.join(scripts_directory, 'test', - 'run_lint_check_css.js'), - ] - - lint_config_files = _getAffectedFiles(input_api, stylelint_related_files, - [], []) - - css_should_bail_out, css_files_to_lint = _getFilesToLint( - input_api, output_api, lint_config_files, default_linted_directories, - ['.css'], results) - - # If there are more than 50 files to check, don't bother and check - # everything, so as to not run into command line length limits on Windows. - if not css_should_bail_out: - if len(css_files_to_lint) < 50: - script_args = ["--files"] + css_files_to_lint - else: - script_args = [] # The defaults check all CSS files. - results.extend( - _checkWithNodeScript(input_api, output_api, lint_path, - script_args)) - - return results - - def _CheckDevToolsNonJSFileLicenseHeaders(input_api, output_api): results = [ output_api.PresubmitNotifyResult( @@ -489,7 +469,13 @@ def _CheckL10nStrings(input_api, output_api): def _CheckNoUncheckedFiles(input_api, output_api): - results = [] + if _IsEnvCog(input_api): + return [ + output_api.PresubmitPromptWarning( + 'Non-git environment detected, skipping ' + '_CheckNoUncheckedFiles.') + ] + process = input_api.subprocess.Popen(['git', 'diff', '--exit-code'], stdout=input_api.subprocess.PIPE, stderr=input_api.subprocess.STDOUT) @@ -591,12 +577,18 @@ def _CannedChecks(canned_checks): def _CommonChecks(canned_checks): local_checks = [ _WithArgs(canned_checks.CheckAuthorizedAuthor, - bot_allowlist=[AUTOROLL_ACCOUNT]), _CheckExperimentTelemetry, - _CheckGeneratedFiles, _CheckDevToolsStyleJS, _CheckDevToolsStyleCSS, - _CheckDevToolsRunESLintTests, _CheckDevToolsRunBuildTests, - _CheckDevToolsNonJSFileLicenseHeaders, _CheckFormat, - _CheckESBuildVersion, _CheckEnumeratedHistograms, - _CheckObsoleteScreenshotGoldens, _CheckNodeModules + bot_allowlist=[AUTOROLL_ACCOUNT]), + _CheckExperimentTelemetry, + _CheckGeneratedFiles, + _CheckDevToolsLint, + _CheckDevToolsRunESLintTests, + _CheckDevToolsRunStylelintTests, + _CheckDevToolsRunBuildTests, + _CheckDevToolsNonJSFileLicenseHeaders, + _CheckFormat, + _CheckESBuildVersion, + _CheckObsoleteScreenshotGoldens, + _CheckNodeModules, ] # Run the canned checks from `depot_tools` after the custom DevTools checks. # The canned checks for example check that lines have line endings. The @@ -656,17 +648,6 @@ def CheckChangeOnUpload(input_api, output_api): _SideEffectChecks, _WithArgs(_CheckBugAssociation, is_committing=False), ] - # Remove check for git once initworkspace is supported in internal repositories - # in Cider. We need this because the subsequent checks will rely on a - # node hook generated by gclient sync. - # TODO(rgw): Remove below check once glcient sync is supported. - if input_api.change.scm != 'git': - return [ - output_api.PresubmitNotifyResult( - 'Non-git workspace detected, skipping CheckChangeOnUpload.' + - 'Remove this check once glcient is supported in internal repositories in Cider.' - ) - ] return _RunAllChecks(checks, input_api, output_api) @@ -738,7 +719,8 @@ def _getFilesToLint(input_api, output_api, lint_config_files, # Exclude front_end/third_party and front_end/generated files. files_to_lint = [ file for file in files_to_lint - if "third_party" not in file or "generated" not in file + if "front_end/third_party" not in file + and "front_end/generated" not in file ] if len(files_to_lint) == 0: diff --git a/build b/build index 7a8285c06acd..e13953ced04e 160000 --- a/build +++ b/build @@ -1 +1 @@ -Subproject commit 7a8285c06acd753e6228263f48e5595e20ca1577 +Subproject commit e13953ced04ed05f45aa3c961bd6d802aced74ec diff --git a/build_overrides/build.gni b/build_overrides/build.gni index bdb6ef866316..195aea483385 100644 --- a/build_overrides/build.gni +++ b/build_overrides/build.gni @@ -10,3 +10,15 @@ build_with_chromium = false ignore_elf32_limitations = true use_system_xcode = true + +# Enables assertions on safety checks in libc++. +# +# This should be set to true whenever building with Chrome's custom libc++ in +# order to guard against undefined behavior. However, the asserts added by +# hardening libc++ may introduce some performance overhead, so this is +# configurable to simplify A/B tests, and to allow performance-sensitive +# projects embedding Chrome (e.g. ANGLE) to disable libc++ hardening. +# +# Note that setting this to true only has an effect when also building with +# `use_custom_libcxx = true`. +enable_safe_libcxx = true diff --git a/buildtools b/buildtools index 3ef44a2b92d5..6f359296daa8 160000 --- a/buildtools +++ b/buildtools @@ -1 +1 @@ -Subproject commit 3ef44a2b92d5dd1faa5189a06f3a5febe6db2d58 +Subproject commit 6f359296daa889aa726f3d05046b9f37be241169 diff --git a/config/gni/devtools_grd_files.gni b/config/gni/devtools_grd_files.gni index 832f55a06a5f..bd55de2bf826 100644 --- a/config/gni/devtools_grd_files.gni +++ b/config/gni/devtools_grd_files.gni @@ -20,6 +20,7 @@ grd_files_release_sources = [ "front_end/Images/accelerometer-left.png", "front_end/Images/accelerometer-right.png", "front_end/Images/accelerometer-top.png", + "front_end/Images/account-tree.svg", "front_end/Images/align-content-center.svg", "front_end/Images/align-content-end.svg", "front_end/Images/align-content-space-around.svg", @@ -36,11 +37,15 @@ grd_files_release_sources = [ "front_end/Images/align-self-end.svg", "front_end/Images/align-self-start.svg", "front_end/Images/align-self-stretch.svg", + "front_end/Images/animation.svg", "front_end/Images/arrow-back.svg", + "front_end/Images/arrow-collapse.svg", "front_end/Images/arrow-down.svg", "front_end/Images/arrow-drop-down-dark.svg", "front_end/Images/arrow-drop-down-light.svg", + "front_end/Images/arrow-drop-down.svg", "front_end/Images/arrow-forward.svg", + "front_end/Images/arrow-right-circle.svg", "front_end/Images/arrow-up-down-circle.svg", "front_end/Images/arrow-up-down.svg", "front_end/Images/arrow-up.svg", @@ -53,10 +58,14 @@ grd_files_release_sources = [ "front_end/Images/breakpoint-circle.svg", "front_end/Images/breakpoint-crossed-filled.svg", "front_end/Images/breakpoint-crossed.svg", + "front_end/Images/brush-2.svg", "front_end/Images/brush-filled.svg", "front_end/Images/brush.svg", "front_end/Images/bug.svg", "front_end/Images/bundle.svg", + "front_end/Images/button-magic.svg", + "front_end/Images/calendar-today.svg", + "front_end/Images/center-focus-weak.svg", "front_end/Images/check-circle.svg", "front_end/Images/check-double.svg", "front_end/Images/checker.svg", @@ -70,6 +79,7 @@ grd_files_release_sources = [ "front_end/Images/chromeLeft.avif", "front_end/Images/chromeMiddle.avif", "front_end/Images/chromeRight.avif", + "front_end/Images/class.svg", "front_end/Images/clear-list.svg", "front_end/Images/clear.svg", "front_end/Images/cloud.svg", @@ -78,10 +88,13 @@ grd_files_release_sources = [ "front_end/Images/colon.svg", "front_end/Images/color-picker-filled.svg", "front_end/Images/color-picker.svg", + "front_end/Images/compress.svg", "front_end/Images/console-conditional-breakpoint.svg", "front_end/Images/console-logpoint.svg", "front_end/Images/cookie.svg", + "front_end/Images/cookie_off.svg", "front_end/Images/copy.svg", + "front_end/Images/corporate-fare.svg", "front_end/Images/credit-card.svg", "front_end/Images/cross-circle-filled.svg", "front_end/Images/cross-circle.svg", @@ -92,13 +105,17 @@ grd_files_release_sources = [ "front_end/Images/deployed.svg", "front_end/Images/device-fold.svg", "front_end/Images/devices.svg", + "front_end/Images/devtools-thumbnail.svg", + "front_end/Images/devtools-tips.svg", "front_end/Images/devtools.svg", + "front_end/Images/difference.svg", "front_end/Images/dock-bottom.svg", "front_end/Images/dock-left.svg", "front_end/Images/dock-right.svg", "front_end/Images/dock-window.svg", "front_end/Images/document.svg", "front_end/Images/dog-paw.svg", + "front_end/Images/domain.svg", "front_end/Images/dots-horizontal.svg", "front_end/Images/dots-vertical.svg", "front_end/Images/download.svg", @@ -139,10 +156,17 @@ grd_files_release_sources = [ "front_end/Images/gear-filled.svg", "front_end/Images/gear.svg", "front_end/Images/gears.svg", + "front_end/Images/global.svg", + "front_end/Images/google.svg", "front_end/Images/goto-filled.svg", + "front_end/Images/grid-on.svg", + "front_end/Images/group.svg", "front_end/Images/heap-snapshot.svg", "front_end/Images/heap-snapshots.svg", "front_end/Images/help.svg", + "front_end/Images/history.svg", + "front_end/Images/home.svg", + "front_end/Images/hover.svg", "front_end/Images/iframe-crossed.svg", "front_end/Images/iframe.svg", "front_end/Images/import.svg", @@ -164,14 +188,17 @@ grd_files_release_sources = [ "front_end/Images/justify-items-start.svg", "front_end/Images/justify-items-stretch.svg", "front_end/Images/keyboard-arrow-right.svg", + "front_end/Images/keyboard-full.svg", "front_end/Images/keyboard-pen.svg", "front_end/Images/keyboard.svg", + "front_end/Images/label.svg", "front_end/Images/large-arrow-right-filled.svg", "front_end/Images/layers-filled.svg", "front_end/Images/layers.svg", "front_end/Images/left-panel-close.svg", "front_end/Images/left-panel-open.svg", "front_end/Images/lightbulb-spark.svg", + "front_end/Images/lightbulb.svg", "front_end/Images/lighthouse_logo.svg", "front_end/Images/list.svg", "front_end/Images/location-on.svg", @@ -185,17 +212,29 @@ grd_files_release_sources = [ "front_end/Images/navigationControls.png", "front_end/Images/navigationControls_2x.png", "front_end/Images/network-settings.svg", + "front_end/Images/node-stack-icon.svg", "front_end/Images/nodeIcon.avif", "front_end/Images/open-externally.svg", + "front_end/Images/override.svg", + "front_end/Images/palette.svg", + "front_end/Images/pause-circle.svg", "front_end/Images/pause.svg", + "front_end/Images/pen-spark.svg", + "front_end/Images/performance-panel-delete-annotation.svg", + "front_end/Images/performance-panel-diagram.svg", + "front_end/Images/performance-panel-entry-label.svg", + "front_end/Images/performance-panel-time-range.svg", "front_end/Images/performance.svg", "front_end/Images/person.svg", + "front_end/Images/photo-camera.svg", "front_end/Images/play.svg", "front_end/Images/plus.svg", + "front_end/Images/policy.svg", "front_end/Images/popoverArrows.png", "front_end/Images/popup.svg", "front_end/Images/preview_feature_video_thumbnail.svg", "front_end/Images/profile.svg", + "front_end/Images/psychiatry.svg", "front_end/Images/react_native/learn-debugging-basics.jpg", "front_end/Images/react_native/learn-native-debugging.jpg", "front_end/Images/react_native/learn-react-native-devtools.jpg", @@ -222,9 +261,9 @@ grd_files_release_sources = [ "front_end/Images/send.svg", "front_end/Images/shadow.svg", "front_end/Images/small-status-dot.svg", + "front_end/Images/smart-assistant.svg", "front_end/Images/snippet.svg", "front_end/Images/spark-info.svg", - "front_end/Images/spark.svg", "front_end/Images/star.svg", "front_end/Images/step-into.svg", "front_end/Images/step-out.svg", @@ -234,8 +273,12 @@ grd_files_release_sources = [ "front_end/Images/symbol.svg", "front_end/Images/sync.svg", "front_end/Images/table.svg", + "front_end/Images/terminal.svg", + "front_end/Images/thumb-down-filled.svg", "front_end/Images/thumb-down.svg", + "front_end/Images/thumb-up-filled.svg", "front_end/Images/thumb-up.svg", + "front_end/Images/tonality.svg", "front_end/Images/toolbarResizerVertical.png", "front_end/Images/top-panel-close.svg", "front_end/Images/top-panel-open.svg", @@ -247,14 +290,16 @@ grd_files_release_sources = [ "front_end/Images/triangle-left.svg", "front_end/Images/triangle-right.svg", "front_end/Images/triangle-up.svg", + "front_end/Images/tune.svg", "front_end/Images/undo.svg", "front_end/Images/warning-filled.svg", "front_end/Images/warning.svg", "front_end/Images/watch.svg", - "front_end/Images/whatsnew.avif", + "front_end/Images/whatsnew.svg", "front_end/Images/width.svg", "front_end/Images/zoom-in.svg", "front_end/Tests.js", + "front_end/application_tokens.css", "front_end/core/common/common.js", "front_end/core/dom_extension/dom_extension.js", "front_end/core/host/host.js", @@ -267,6 +312,7 @@ grd_files_release_sources = [ "front_end/core/root/root.js", "front_end/core/sdk/sdk-meta.js", "front_end/core/sdk/sdk.js", + "front_end/design_system_tokens.css", "front_end/device_mode_emulation_frame.html", "front_end/devtools_app.html", "front_end/devtools_compatibility.js", @@ -326,6 +372,7 @@ grd_files_release_sources = [ "front_end/entrypoints/main/main.js", "front_end/entrypoints/ndb_app/ndb_app.js", "front_end/entrypoints/node_app/node_app.js", + "front_end/entrypoints/rehydrated_devtools_app/rehydrated_devtools_app.js", "front_end/entrypoints/rn_fusebox/rn_fusebox.js", "front_end/entrypoints/rn_inspector/rn_inspector.js", "front_end/entrypoints/shell/shell.js", @@ -337,6 +384,7 @@ grd_files_release_sources = [ "front_end/js_app.html", "front_end/legacy_test_runner/legacy_test_runner.js", "front_end/legacy_test_runner/test_runner/test_runner.js", + "front_end/models/ai_assistance/ai_assistance.js", "front_end/models/autofill_manager/autofill_manager.js", "front_end/models/bindings/bindings.js", "front_end/models/breakpoints/breakpoints.js", @@ -369,11 +417,18 @@ grd_files_release_sources = [ "front_end/models/issues_manager/descriptions/SameSiteWarnCrossDowngradeSet.md", "front_end/models/issues_manager/descriptions/SameSiteWarnStrictLaxDowngradeStrict.md", "front_end/models/issues_manager/descriptions/arInsecureContext.md", + "front_end/models/issues_manager/descriptions/arInvalidInfoHeader.md", "front_end/models/issues_manager/descriptions/arInvalidRegisterOsSourceHeader.md", "front_end/models/issues_manager/descriptions/arInvalidRegisterOsTriggerHeader.md", "front_end/models/issues_manager/descriptions/arInvalidRegisterSourceHeader.md", "front_end/models/issues_manager/descriptions/arInvalidRegisterTriggerHeader.md", + "front_end/models/issues_manager/descriptions/arNavigationRegistrationUniqueScopeAlreadySet.md", "front_end/models/issues_manager/descriptions/arNavigationRegistrationWithoutTransientUserActivation.md", + "front_end/models/issues_manager/descriptions/arNoRegisterOsSourceHeader.md", + "front_end/models/issues_manager/descriptions/arNoRegisterOsTriggerHeader.md", + "front_end/models/issues_manager/descriptions/arNoRegisterSourceHeader.md", + "front_end/models/issues_manager/descriptions/arNoRegisterTriggerHeader.md", + "front_end/models/issues_manager/descriptions/arNoWebOrOsSupport.md", "front_end/models/issues_manager/descriptions/arOsSourceIgnored.md", "front_end/models/issues_manager/descriptions/arOsTriggerIgnored.md", "front_end/models/issues_manager/descriptions/arPermissionPolicyDisabled.md", @@ -388,6 +443,8 @@ grd_files_release_sources = [ "front_end/models/issues_manager/descriptions/cookieCrossSiteRedirectDowngrade.md", "front_end/models/issues_manager/descriptions/cookieExcludeBlockedWithinRelatedWebsiteSet.md", "front_end/models/issues_manager/descriptions/cookieExcludeDomainNonAscii.md", + "front_end/models/issues_manager/descriptions/cookieExcludePortMismatch.md", + "front_end/models/issues_manager/descriptions/cookieExcludeSchemeMismatch.md", "front_end/models/issues_manager/descriptions/cookieExcludeThirdPartyPhaseoutRead.md", "front_end/models/issues_manager/descriptions/cookieExcludeThirdPartyPhaseoutSet.md", "front_end/models/issues_manager/descriptions/cookieWarnDomainNonAscii.md", @@ -401,6 +458,7 @@ grd_files_release_sources = [ "front_end/models/issues_manager/descriptions/corsHeaderDisallowedByPreflightResponse.md", "front_end/models/issues_manager/descriptions/corsInsecurePrivateNetwork.md", "front_end/models/issues_manager/descriptions/corsInvalidHeaderValues.md", + "front_end/models/issues_manager/descriptions/corsLocalNetworkAccessPermissionDenied.md", "front_end/models/issues_manager/descriptions/corsMethodDisallowedByPreflightResponse.md", "front_end/models/issues_manager/descriptions/corsNoCorsRedirectModeNotFollow.md", "front_end/models/issues_manager/descriptions/corsOriginMismatch.md", @@ -443,6 +501,7 @@ grd_files_release_sources = [ "front_end/models/issues_manager/descriptions/federatedAuthUserInfoRequestNotPotentiallyTrustworthy.md", "front_end/models/issues_manager/descriptions/federatedAuthUserInfoRequestNotSameOrigin.md", "front_end/models/issues_manager/descriptions/federatedAuthUserInfoRequestNotSignedInWithIdp.md", + "front_end/models/issues_manager/descriptions/fetchingPartitionedBlobURL.md", "front_end/models/issues_manager/descriptions/genericFormAriaLabelledByToNonExistingId.md", "front_end/models/issues_manager/descriptions/genericFormAutocompleteAttributeEmptyError.md", "front_end/models/issues_manager/descriptions/genericFormDuplicateIdForInputError.md", @@ -456,8 +515,16 @@ grd_files_release_sources = [ "front_end/models/issues_manager/descriptions/genericResponseWasBlockedByORB.md", "front_end/models/issues_manager/descriptions/heavyAd.md", "front_end/models/issues_manager/descriptions/mixedContent.md", + "front_end/models/issues_manager/descriptions/navigatingPartitionedBlobURL.md", + "front_end/models/issues_manager/descriptions/placeholderDescriptionForInvisibleIssues.md", "front_end/models/issues_manager/descriptions/propertyRuleInvalidNameIssue.md", "front_end/models/issues_manager/descriptions/propertyRuleIssue.md", + "front_end/models/issues_manager/descriptions/selectElementAccessibilityDisallowedOptGroupChild.md", + "front_end/models/issues_manager/descriptions/selectElementAccessibilityDisallowedSelectChild.md", + "front_end/models/issues_manager/descriptions/selectElementAccessibilityInteractiveContentAttributesSelectDescendant.md", + "front_end/models/issues_manager/descriptions/selectElementAccessibilityInteractiveContentLegendChild.md", + "front_end/models/issues_manager/descriptions/selectElementAccessibilityInteractiveContentOptionChild.md", + "front_end/models/issues_manager/descriptions/selectElementAccessibilityNonPhrasingContentOptionChild.md", "front_end/models/issues_manager/descriptions/sharedArrayBuffer.md", "front_end/models/issues_manager/descriptions/sharedDictionaryUseErrorCrossOriginNoCorsRequest.md", "front_end/models/issues_manager/descriptions/sharedDictionaryUseErrorDictionaryLoadFailure.md", @@ -482,6 +549,27 @@ grd_files_release_sources = [ "front_end/models/issues_manager/descriptions/sharedDictionaryWriteErrorShuttingDown.md", "front_end/models/issues_manager/descriptions/sharedDictionaryWriteErrorTooLongIdField.md", "front_end/models/issues_manager/descriptions/sharedDictionaryWriteErrorUnsupportedType.md", + "front_end/models/issues_manager/descriptions/sriInvalidSignatureHeader.md", + "front_end/models/issues_manager/descriptions/sriInvalidSignatureInputHeader.md", + "front_end/models/issues_manager/descriptions/sriMissingSignatureHeader.md", + "front_end/models/issues_manager/descriptions/sriMissingSignatureInputHeader.md", + "front_end/models/issues_manager/descriptions/sriSignatureHeaderValueIsIncorrectLength.md", + "front_end/models/issues_manager/descriptions/sriSignatureHeaderValueIsNotByteSequence.md", + "front_end/models/issues_manager/descriptions/sriSignatureHeaderValueIsParameterized.md", + "front_end/models/issues_manager/descriptions/sriSignatureInputHeaderInvalidComponentName.md", + "front_end/models/issues_manager/descriptions/sriSignatureInputHeaderInvalidComponentType.md", + "front_end/models/issues_manager/descriptions/sriSignatureInputHeaderInvalidDerivedComponentParameter.md", + "front_end/models/issues_manager/descriptions/sriSignatureInputHeaderInvalidHeaderComponentParameter.md", + "front_end/models/issues_manager/descriptions/sriSignatureInputHeaderInvalidParameter.md", + "front_end/models/issues_manager/descriptions/sriSignatureInputHeaderKeyIdLength.md", + "front_end/models/issues_manager/descriptions/sriSignatureInputHeaderMissingLabel.md", + "front_end/models/issues_manager/descriptions/sriSignatureInputHeaderMissingRequiredParameters.md", + "front_end/models/issues_manager/descriptions/sriSignatureInputHeaderValueMissingComponents.md", + "front_end/models/issues_manager/descriptions/sriSignatureInputHeaderValueNotInnerList.md", + "front_end/models/issues_manager/descriptions/sriValidationFailedIntegrityMismatch.md", + "front_end/models/issues_manager/descriptions/sriValidationFailedInvalidLength.md", + "front_end/models/issues_manager/descriptions/sriValidationFailedSignatureExpired.md", + "front_end/models/issues_manager/descriptions/sriValidationFailedSignatureMismatch.md", "front_end/models/issues_manager/descriptions/stylesheetLateImport.md", "front_end/models/issues_manager/descriptions/stylesheetRequestFailed.md", "front_end/models/issues_manager/issues_manager.js", @@ -493,10 +581,10 @@ grd_files_release_sources = [ "front_end/models/logs/logs.js", "front_end/models/persistence/persistence-meta.js", "front_end/models/persistence/persistence.js", + "front_end/models/project_settings/project_settings.js", "front_end/models/react_native/react_native.js", "front_end/models/source_map_scopes/source_map_scopes.js", "front_end/models/text_utils/text_utils.js", - "front_end/models/timeline_model/timeline_model.js", "front_end/models/trace/extras/extras.js", "front_end/models/trace/handlers/handlers.js", "front_end/models/trace/helpers/helpers.js", @@ -507,7 +595,6 @@ grd_files_release_sources = [ "front_end/models/trace/lantern/metrics/metrics.js", "front_end/models/trace/lantern/simulation/simulation.js", "front_end/models/trace/lantern/types/types.js", - "front_end/models/trace/root-causes/root-causes.js", "front_end/models/trace/trace.js", "front_end/models/trace/types/types.js", "front_end/models/workspace/workspace.js", @@ -516,6 +603,8 @@ grd_files_release_sources = [ "front_end/node_app.html", "front_end/panels/accessibility/accessibility-meta.js", "front_end/panels/accessibility/accessibility.js", + "front_end/panels/ai_assistance/ai_assistance-meta.js", + "front_end/panels/ai_assistance/ai_assistance.js", "front_end/panels/animation/animation-meta.js", "front_end/panels/animation/animation.js", "front_end/panels/application/application-meta.js", @@ -529,6 +618,7 @@ grd_files_release_sources = [ "front_end/panels/browser_debugger/browser_debugger.js", "front_end/panels/changes/changes-meta.js", "front_end/panels/changes/changes.js", + "front_end/panels/common/common.js", "front_end/panels/console/console-meta.js", "front_end/panels/console/console.js", "front_end/panels/console_counters/console_counters-meta.js", @@ -549,8 +639,6 @@ grd_files_release_sources = [ "front_end/panels/event_listeners/event_listeners.js", "front_end/panels/explain/explain-meta.js", "front_end/panels/explain/explain.js", - "front_end/panels/freestyler/freestyler-meta.js", - "front_end/panels/freestyler/freestyler.js", "front_end/panels/issues/components/components.js", "front_end/panels/issues/issues-meta.js", "front_end/panels/issues/issues.js", @@ -577,12 +665,11 @@ grd_files_release_sources = [ "front_end/panels/performance_monitor/performance_monitor.js", "front_end/panels/profiler/profiler-meta.js", "front_end/panels/profiler/profiler.js", - "front_end/panels/protocol_monitor/components/components.js", "front_end/panels/protocol_monitor/protocol_monitor-meta.js", "front_end/panels/protocol_monitor/protocol_monitor.js", + "front_end/panels/react_devtools/react_devtools.js", "front_end/panels/react_devtools/react_devtools_components-meta.js", "front_end/panels/react_devtools/react_devtools_profiler-meta.js", - "front_end/panels/react_devtools/react_devtools.js", "front_end/panels/recorder/components/components.js", "front_end/panels/recorder/controllers/controllers.js", "front_end/panels/recorder/converters/converters.js", @@ -629,6 +716,10 @@ grd_files_release_sources = [ "front_end/panels/web_audio/web_audio.js", "front_end/panels/webauthn/webauthn-meta.js", "front_end/panels/webauthn/webauthn.js", + "front_end/panels/whats_new/resources/WNDT.md", + "front_end/panels/whats_new/whats_new-meta.js", + "front_end/panels/whats_new/whats_new.js", + "front_end/rehydrated_devtools_app.html", "front_end/rn_fusebox.html", "front_end/rn_inspector.html", "front_end/services/puppeteer/puppeteer.js", @@ -656,6 +747,8 @@ grd_files_release_sources = [ "front_end/third_party/diff/diff.js", "front_end/third_party/i18n/i18n.js", "front_end/third_party/intl-messageformat/intl-messageformat.js", + "front_end/third_party/json5/json5.js", + "front_end/third_party/legacy-javascript/legacy-javascript.js", "front_end/third_party/lighthouse/lighthouse-dt-bundle.js", "front_end/third_party/lighthouse/report/report.js", "front_end/third_party/lit/lit.js", @@ -663,16 +756,18 @@ grd_files_release_sources = [ "front_end/third_party/puppeteer-replay/puppeteer-replay.js", "front_end/third_party/puppeteer/puppeteer.js", "front_end/third_party/react-devtools/react-devtools.js", + "front_end/third_party/third-party-web/third-party-web.js", "front_end/third_party/wasmparser/wasmparser.js", "front_end/third_party/web-vitals/web-vitals.js", "front_end/ui/components/adorners/adorners.js", "front_end/ui/components/buttons/buttons.js", + "front_end/ui/components/cards/cards.js", "front_end/ui/components/chrome_link/chrome_link.js", "front_end/ui/components/code_highlighter/code_highlighter.js", - "front_end/ui/components/data_grid/data_grid.js", "front_end/ui/components/dialogs/dialogs.js", "front_end/ui/components/diff_view/diff_view.js", "front_end/ui/components/expandable_list/expandable_list.js", + "front_end/ui/components/floating_button/floating_button.js", "front_end/ui/components/helpers/helpers.js", "front_end/ui/components/highlighting/highlighting.js", "front_end/ui/components/icon_button/icon_button.js", @@ -689,14 +784,15 @@ grd_files_release_sources = [ "front_end/ui/components/report_view/report_view.js", "front_end/ui/components/request_link_icon/request_link_icon.js", "front_end/ui/components/settings/settings.js", - "front_end/ui/components/split_view/split_view.js", + "front_end/ui/components/spinners/spinners.js", "front_end/ui/components/srgb_overlay/srgb_overlay.js", "front_end/ui/components/suggestion_input/suggestion_input.js", "front_end/ui/components/survey_link/survey_link.js", + "front_end/ui/components/switch/switch.js", "front_end/ui/components/text_editor/text_editor.js", "front_end/ui/components/text_prompt/text_prompt.js", + "front_end/ui/components/tooltips/tooltips.js", "front_end/ui/components/tree_outline/tree_outline.js", - "front_end/ui/components/two_states_counter/two_states_counter.js", "front_end/ui/legacy/components/color_picker/color_picker.js", "front_end/ui/legacy/components/cookie_table/cookie_table.js", "front_end/ui/legacy/components/data_grid/data_grid.js", @@ -712,7 +808,7 @@ grd_files_release_sources = [ "front_end/ui/legacy/components/utils/utils.js", "front_end/ui/legacy/legacy.js", "front_end/ui/legacy/theme_support/theme_support.js", - "front_end/ui/lit-html/lit-html.js", + "front_end/ui/lit/lit.js", "front_end/ui/visual_logging/visual_logging.js", "front_end/worker_app.html", ] @@ -731,6 +827,7 @@ grd_files_debug_sources = [ "front_end/core/common/JavaScriptMetaData.js", "front_end/core/common/Lazy.js", "front_end/core/common/Linkifier.js", + "front_end/core/common/MapWithDefault.js", "front_end/core/common/Mutex.js", "front_end/core/common/Object.js", "front_end/core/common/ParsedURL.js", @@ -757,7 +854,9 @@ grd_files_debug_sources = [ "front_end/core/host/RNPerfMetrics.js", "front_end/core/host/ResourceLoader.js", "front_end/core/host/UserMetrics.js", + "front_end/core/i18n/ByteUtilities.js", "front_end/core/i18n/DevToolsLocale.js", + "front_end/core/i18n/NumberFormatter.js", "front_end/core/i18n/i18nImpl.js", "front_end/core/i18n/i18nTypes.js", "front_end/core/i18n/locales.js", @@ -765,6 +864,7 @@ grd_files_debug_sources = [ "front_end/core/i18n/time-utilities.js", "front_end/core/platform/ArrayUtilities.js", "front_end/core/platform/Brand.js", + "front_end/core/platform/Constructor.js", "front_end/core/platform/DOMUtilities.js", "front_end/core/platform/DateUtilities.js", "front_end/core/platform/DevToolsPath.js", @@ -772,7 +872,6 @@ grd_files_debug_sources = [ "front_end/core/platform/MapUtilities.js", "front_end/core/platform/MimeType.js", "front_end/core/platform/NumberUtilities.js", - "front_end/core/platform/PromiseUtilities.js", "front_end/core/platform/StringUtilities.js", "front_end/core/platform/Timing.js", "front_end/core/platform/TypedArrayUtilities.js", @@ -781,11 +880,11 @@ grd_files_debug_sources = [ "front_end/core/platform/UserVisibleError.js", "front_end/core/protocol_client/InspectorBackend.js", "front_end/core/protocol_client/NodeURL.js", - "front_end/core/root/Runtime.js", "front_end/core/rn_experiments/experimentsImpl.js", + "front_end/core/root/Runtime.js", "front_end/core/sdk/AccessibilityModel.js", + "front_end/core/sdk/AnimationModel.js", "front_end/core/sdk/AutofillModel.js", - "front_end/core/sdk/CPUProfileDataModel.js", "front_end/core/sdk/CPUProfilerModel.js", "front_end/core/sdk/CPUThrottlingManager.js", "front_end/core/sdk/CSSContainerQuery.js", @@ -797,6 +896,7 @@ grd_files_debug_sources = [ "front_end/core/sdk/CSSModel.js", "front_end/core/sdk/CSSProperty.js", "front_end/core/sdk/CSSPropertyParser.js", + "front_end/core/sdk/CSSPropertyParserMatchers.js", "front_end/core/sdk/CSSQuery.js", "front_end/core/sdk/CSSRule.js", "front_end/core/sdk/CSSScope.js", @@ -816,6 +916,7 @@ grd_files_debug_sources = [ "front_end/core/sdk/DOMModel.js", "front_end/core/sdk/DebuggerModel.js", "front_end/core/sdk/EmulationModel.js", + "front_end/core/sdk/EnhancedTracesParser.js", "front_end/core/sdk/EventBreakpointsModel.js", "front_end/core/sdk/FrameAssociated.js", "front_end/core/sdk/FrameManager.js", @@ -836,8 +937,9 @@ grd_files_debug_sources = [ "front_end/core/sdk/PaintProfiler.js", "front_end/core/sdk/PerformanceMetricsModel.js", "front_end/core/sdk/PreloadingModel.js", - "front_end/core/sdk/ProfileTreeModel.js", "front_end/core/sdk/ReactNativeApplicationModel.js", + "front_end/core/sdk/RehydratingConnection.js", + "front_end/core/sdk/RehydratingObject.js", "front_end/core/sdk/RemoteObject.js", "front_end/core/sdk/Resource.js", "front_end/core/sdk/ResourceTreeModel.js", @@ -852,13 +954,16 @@ grd_files_debug_sources = [ "front_end/core/sdk/ServiceWorkerCacheModel.js", "front_end/core/sdk/ServiceWorkerManager.js", "front_end/core/sdk/SourceMap.js", + "front_end/core/sdk/SourceMapFunctionRanges.js", "front_end/core/sdk/SourceMapManager.js", + "front_end/core/sdk/SourceMapScopeChainEntry.js", "front_end/core/sdk/SourceMapScopes.js", "front_end/core/sdk/SourceMapScopesInfo.js", "front_end/core/sdk/StorageBucketsModel.js", "front_end/core/sdk/StorageKeyManager.js", "front_end/core/sdk/Target.js", "front_end/core/sdk/TargetManager.js", + "front_end/core/sdk/TraceObject.js", "front_end/core/sdk/WebAuthnModel.js", "front_end/entrypoints/formatter_worker/AcornTokenizer.js", "front_end/entrypoints/formatter_worker/CSSFormatter.js", @@ -885,7 +990,6 @@ grd_files_debug_sources = [ "front_end/entrypoints/lighthouse_worker/LighthouseWorkerService.js", "front_end/entrypoints/main/ExecutionContextSelector.js", "front_end/entrypoints/main/MainImpl.js", - "front_end/entrypoints/main/SettingTracker.js", "front_end/entrypoints/main/SimpleApp.js", "front_end/entrypoints/node_app/NodeConnectionsPanel.js", "front_end/entrypoints/node_app/NodeMain.js", @@ -903,6 +1007,24 @@ grd_files_debug_sources = [ "front_end/generated/SupportedCSSProperties.js", "front_end/generated/protocol.js", "front_end/legacy_test_runner/test_runner/TestRunner.js", + "front_end/models/ai_assistance/AgentProject.js", + "front_end/models/ai_assistance/AiHistoryStorage.js", + "front_end/models/ai_assistance/ChangeManager.js", + "front_end/models/ai_assistance/EvaluateAction.js", + "front_end/models/ai_assistance/ExtensionScope.js", + "front_end/models/ai_assistance/agents/AiAgent.js", + "front_end/models/ai_assistance/agents/FileAgent.js", + "front_end/models/ai_assistance/agents/NetworkAgent.js", + "front_end/models/ai_assistance/agents/PatchAgent.js", + "front_end/models/ai_assistance/agents/PerformanceAgent.js", + "front_end/models/ai_assistance/agents/PerformanceAnnotationsAgent.js", + "front_end/models/ai_assistance/agents/PerformanceInsightsAgent.js", + "front_end/models/ai_assistance/agents/StylingAgent.js", + "front_end/models/ai_assistance/data_formatters/FileFormatter.js", + "front_end/models/ai_assistance/data_formatters/NetworkRequestFormatter.js", + "front_end/models/ai_assistance/data_formatters/PerformanceInsightFormatter.js", + "front_end/models/ai_assistance/debug.js", + "front_end/models/ai_assistance/injected.js", "front_end/models/autofill_manager/AutofillManager.js", "front_end/models/bindings/CSSWorkspaceBinding.js", "front_end/models/bindings/CompilerScriptMapping.js", @@ -965,23 +1087,27 @@ grd_files_debug_sources = [ "front_end/models/issues_manager/LowTextContrastIssue.js", "front_end/models/issues_manager/MarkdownIssueDescription.js", "front_end/models/issues_manager/MixedContentIssue.js", + "front_end/models/issues_manager/PartitioningBlobURLIssue.js", "front_end/models/issues_manager/PropertyRuleIssue.js", "front_end/models/issues_manager/QuirksModeIssue.js", "front_end/models/issues_manager/RelatedIssue.js", + "front_end/models/issues_manager/SRIMessageSignatureIssue.js", + "front_end/models/issues_manager/SelectElementAccessibilityIssue.js", "front_end/models/issues_manager/SharedArrayBufferIssue.js", "front_end/models/issues_manager/SharedDictionaryIssue.js", "front_end/models/issues_manager/SourceFrameIssuesManager.js", "front_end/models/issues_manager/StylesheetLoadingIssue.js", - "front_end/models/javascript_metadata/DOMPinnedProperties.js", "front_end/models/javascript_metadata/JavaScriptMetadata.js", "front_end/models/javascript_metadata/NativeFunctions.js", "front_end/models/live-metrics/LiveMetrics.js", "front_end/models/live-metrics/web-vitals-injected/OnEachInteraction.js", + "front_end/models/live-metrics/web-vitals-injected/OnEachLayoutShift.js", "front_end/models/live-metrics/web-vitals-injected/web-vitals-injected.js", "front_end/models/logs/LogManager.js", "front_end/models/logs/NetworkLog.js", "front_end/models/logs/RequestResolver.js", "front_end/models/persistence/Automapping.js", + "front_end/models/persistence/AutomaticFileSystemManager.js", "front_end/models/persistence/EditFileSystemView.js", "front_end/models/persistence/FileSystemWorkspaceBinding.js", "front_end/models/persistence/IsolatedFileSystem.js", @@ -994,6 +1120,7 @@ grd_files_debug_sources = [ "front_end/models/persistence/WorkspaceSettingsTab.js", "front_end/models/persistence/editFileSystemView.css.js", "front_end/models/persistence/workspaceSettingsTab.css.js", + "front_end/models/project_settings/ProjectSettingsModel.js", "front_end/models/react_native/ReactDevToolsBindingsModel.js", "front_end/models/source_map_scopes/NamesResolver.js", "front_end/models/source_map_scopes/ScopeChainModel.js", @@ -1008,11 +1135,6 @@ grd_files_debug_sources = [ "front_end/models/text_utils/TextRange.js", "front_end/models/text_utils/TextUtils.js", "front_end/models/text_utils/WasmDisassembly.js", - "front_end/models/timeline_model/TimelineJSProfile.js", - "front_end/models/timeline_model/TimelineModelFilter.js", - "front_end/models/timeline_model/TimelineProfileTree.js", - "front_end/models/timeline_model/TracingLayerTree.js", - "front_end/models/trace/EntriesFilter.js", "front_end/models/trace/LanternComputationData.js", "front_end/models/trace/ModelImpl.js", "front_end/models/trace/Processor.js", @@ -1021,11 +1143,18 @@ grd_files_debug_sources = [ "front_end/models/trace/extras/FilmStrip.js", "front_end/models/trace/extras/MainThreadActivity.js", "front_end/models/trace/extras/Metadata.js", - "front_end/models/trace/extras/URLForEntry.js", + "front_end/models/trace/extras/ScriptDuplication.js", + "front_end/models/trace/extras/StackTraceForEvent.js", + "front_end/models/trace/extras/ThirdParties.js", + "front_end/models/trace/extras/TraceFilter.js", + "front_end/models/trace/extras/TraceTree.js", + "front_end/models/trace/handlers/AnimationFramesHandler.js", "front_end/models/trace/handlers/AnimationHandler.js", + "front_end/models/trace/handlers/AsyncJSCallsHandler.js", "front_end/models/trace/handlers/AuctionWorkletsHandler.js", - "front_end/models/trace/handlers/EnhancedTracesHandler.js", + "front_end/models/trace/handlers/DOMStatsHandler.js", "front_end/models/trace/handlers/ExtensionTraceDataHandler.js", + "front_end/models/trace/handlers/FlowsHandler.js", "front_end/models/trace/handlers/FramesHandler.js", "front_end/models/trace/handlers/GPUHandler.js", "front_end/models/trace/handlers/ImagePaintingHandler.js", @@ -1044,12 +1173,14 @@ grd_files_debug_sources = [ "front_end/models/trace/handlers/RendererHandler.js", "front_end/models/trace/handlers/SamplesHandler.js", "front_end/models/trace/handlers/ScreenshotsHandler.js", + "front_end/models/trace/handlers/ScriptsHandler.js", "front_end/models/trace/handlers/SelectorStatsHandler.js", "front_end/models/trace/handlers/Threads.js", "front_end/models/trace/handlers/UserInteractionsHandler.js", "front_end/models/trace/handlers/UserTimingsHandler.js", "front_end/models/trace/handlers/WarningsHandler.js", "front_end/models/trace/handlers/WorkersHandler.js", + "front_end/models/trace/handlers/helpers.js", "front_end/models/trace/handlers/types.js", "front_end/models/trace/helpers/Extensions.js", "front_end/models/trace/helpers/Network.js", @@ -1058,12 +1189,26 @@ grd_files_debug_sources = [ "front_end/models/trace/helpers/Timing.js", "front_end/models/trace/helpers/Trace.js", "front_end/models/trace/helpers/TreeHelpers.js", - "front_end/models/trace/insights/CumulativeLayoutShift.js", + "front_end/models/trace/insights/CLSCulprits.js", + "front_end/models/trace/insights/Cache.js", + "front_end/models/trace/insights/Common.js", + "front_end/models/trace/insights/DOMSize.js", "front_end/models/trace/insights/DocumentLatency.js", - "front_end/models/trace/insights/InsightRunners.js", + "front_end/models/trace/insights/DuplicatedJavaScript.js", + "front_end/models/trace/insights/FontDisplay.js", + "front_end/models/trace/insights/ForcedReflow.js", + "front_end/models/trace/insights/ImageDelivery.js", "front_end/models/trace/insights/InteractionToNextPaint.js", - "front_end/models/trace/insights/LargestContentfulPaint.js", + "front_end/models/trace/insights/LCPDiscovery.js", + "front_end/models/trace/insights/LCPPhases.js", + "front_end/models/trace/insights/LegacyJavaScript.js", + "front_end/models/trace/insights/Models.js", + "front_end/models/trace/insights/ModernHTTP.js", + "front_end/models/trace/insights/NetworkDependencyTree.js", "front_end/models/trace/insights/RenderBlocking.js", + "front_end/models/trace/insights/SlowCSSSelector.js", + "front_end/models/trace/insights/Statistics.js", + "front_end/models/trace/insights/ThirdParties.js", "front_end/models/trace/insights/Viewport.js", "front_end/models/trace/insights/types.js", "front_end/models/trace/lantern/core/LanternError.js", @@ -1087,8 +1232,6 @@ grd_files_debug_sources = [ "front_end/models/trace/lantern/simulation/Simulator.js", "front_end/models/trace/lantern/simulation/TCPConnection.js", "front_end/models/trace/lantern/types/Lantern.js", - "front_end/models/trace/root-causes/LayoutShift.js", - "front_end/models/trace/root-causes/RootCauses.js", "front_end/models/trace/types/Configuration.js", "front_end/models/trace/types/Extensions.js", "front_end/models/trace/types/File.js", @@ -1110,9 +1253,15 @@ grd_files_debug_sources = [ "front_end/panels/accessibility/accessibilityNode.css.js", "front_end/panels/accessibility/accessibilityProperties.css.js", "front_end/panels/accessibility/axBreadcrumbs.css.js", - "front_end/panels/animation/AnimationDOMNode.js", + "front_end/panels/ai_assistance/AiAssistancePanel.js", + "front_end/panels/ai_assistance/PatchWidget.js", + "front_end/panels/ai_assistance/aiAssistancePanel.css.js", + "front_end/panels/ai_assistance/components/ChatView.js", + "front_end/panels/ai_assistance/components/MarkdownRendererWithCodeBlock.js", + "front_end/panels/ai_assistance/components/UserActionRow.js", + "front_end/panels/ai_assistance/components/chatView.css.js", + "front_end/panels/ai_assistance/components/userActionRow.css.js", "front_end/panels/animation/AnimationGroupPreviewUI.js", - "front_end/panels/animation/AnimationModel.js", "front_end/panels/animation/AnimationScreenshotPopover.js", "front_end/panels/animation/AnimationTimeline.js", "front_end/panels/animation/AnimationUI.js", @@ -1128,11 +1277,14 @@ grd_files_debug_sources = [ "front_end/panels/application/CookieItemsView.js", "front_end/panels/application/DOMStorageItemsView.js", "front_end/panels/application/DOMStorageModel.js", + "front_end/panels/application/ExtensionStorageItemsView.js", + "front_end/panels/application/ExtensionStorageModel.js", "front_end/panels/application/IndexedDBModel.js", "front_end/panels/application/IndexedDBViews.js", "front_end/panels/application/InterestGroupStorageModel.js", "front_end/panels/application/InterestGroupStorageView.js", "front_end/panels/application/InterestGroupTreeElement.js", + "front_end/panels/application/KeyValueStorageItemsView.js", "front_end/panels/application/OpenedWindowDetailsView.js", "front_end/panels/application/PreloadingTreeElement.js", "front_end/panels/application/ReportingApiReportsView.js", @@ -1209,7 +1361,6 @@ grd_files_debug_sources = [ "front_end/panels/application/preloading/helper/PreloadingForward.js", "front_end/panels/application/preloading/preloadingView.css.js", "front_end/panels/application/preloading/preloadingViewDropDown.css.js", - "front_end/panels/application/reportingApiReportsView.css.js", "front_end/panels/application/resourcesPanel.css.js", "front_end/panels/application/resourcesSidebar.css.js", "front_end/panels/application/serviceWorkerCacheViews.css.js", @@ -1230,8 +1381,11 @@ grd_files_debug_sources = [ "front_end/panels/browser_debugger/xhrBreakpointsSidebarPane.css.js", "front_end/panels/changes/ChangesSidebar.js", "front_end/panels/changes/ChangesView.js", + "front_end/panels/changes/CombinedDiffView.js", "front_end/panels/changes/changesSidebar.css.js", "front_end/panels/changes/changesView.css.js", + "front_end/panels/changes/combinedDiffView.css.js", + "front_end/panels/common/common.css.js", "front_end/panels/console/ConsoleContextSelector.js", "front_end/panels/console/ConsoleFilter.js", "front_end/panels/console/ConsoleFormat.js", @@ -1276,12 +1430,14 @@ grd_files_debug_sources = [ "front_end/panels/elements/AccessibilityTreeView.js", "front_end/panels/elements/CSSRuleValidator.js", "front_end/panels/elements/CSSRuleValidatorHelper.js", + "front_end/panels/elements/CSSValueTraceView.js", "front_end/panels/elements/ClassesPaneWidget.js", "front_end/panels/elements/ColorSwatchPopoverIcon.js", "front_end/panels/elements/ComputedStyleModel.js", "front_end/panels/elements/ComputedStyleWidget.js", "front_end/panels/elements/DOMLinkifier.js", "front_end/panels/elements/DOMPath.js", + "front_end/panels/elements/ElementIssueUtils.js", "front_end/panels/elements/ElementStatePaneWidget.js", "front_end/panels/elements/ElementsPanel.js", "front_end/panels/elements/ElementsSidebarPane.js", @@ -1297,7 +1453,6 @@ grd_files_debug_sources = [ "front_end/panels/elements/NodeStackTraceWidget.js", "front_end/panels/elements/PlatformFontsWidget.js", "front_end/panels/elements/PropertiesWidget.js", - "front_end/panels/elements/PropertyMatchers.js", "front_end/panels/elements/PropertyNameCategories.js", "front_end/panels/elements/PropertyRenderer.js", "front_end/panels/elements/StyleEditorWidget.js", @@ -1312,7 +1467,6 @@ grd_files_debug_sources = [ "front_end/panels/elements/classesPaneWidget.css.js", "front_end/panels/elements/components/AccessibilityTreeNode.js", "front_end/panels/elements/components/AdornerManager.js", - "front_end/panels/elements/components/AdornerSettingsPane.js", "front_end/panels/elements/components/AnchorFunctionLinkSwatch.js", "front_end/panels/elements/components/CSSHintDetailsView.js", "front_end/panels/elements/components/CSSPropertyDocsView.js", @@ -1330,7 +1484,6 @@ grd_files_debug_sources = [ "front_end/panels/elements/components/QueryContainer.js", "front_end/panels/elements/components/StylePropertyEditor.js", "front_end/panels/elements/components/accessibilityTreeNode.css.js", - "front_end/panels/elements/components/adornerSettingsPane.css.js", "front_end/panels/elements/components/anchorFunctionLinkSwatch.css.js", "front_end/panels/elements/components/computedStyleProperty.css.js", "front_end/panels/elements/components/computedStyleTrace.css.js", @@ -1344,6 +1497,7 @@ grd_files_debug_sources = [ "front_end/panels/elements/components/queryContainer.css.js", "front_end/panels/elements/components/stylePropertyEditor.css.js", "front_end/panels/elements/computedStyleSidebarPane.css.js", + "front_end/panels/elements/cssValueTraceView.css.js", "front_end/panels/elements/domLinkifier.css.js", "front_end/panels/elements/elementStatePaneWidget.css.js", "front_end/panels/elements/elementsPanel.css.js", @@ -1362,10 +1516,9 @@ grd_files_debug_sources = [ "front_end/panels/emulation/InspectedPagePlaceholder.js", "front_end/panels/emulation/MediaQueryInspector.js", "front_end/panels/emulation/components/DeviceSizeInputElement.js", - "front_end/panels/emulation/deviceModeToolbar.css.legacy.js", - "front_end/panels/emulation/deviceModeView.css.legacy.js", - "front_end/panels/emulation/inspectedPagePlaceholder.css.legacy.js", - "front_end/panels/emulation/mediaQueryInspector.css.legacy.js", + "front_end/panels/emulation/deviceModeView.css.js", + "front_end/panels/emulation/inspectedPagePlaceholder.css.js", + "front_end/panels/emulation/mediaQueryInspector.css.js", "front_end/panels/event_listeners/EventListenersUtils.js", "front_end/panels/event_listeners/EventListenersView.js", "front_end/panels/event_listeners/eventListenersView.css.js", @@ -1374,22 +1527,16 @@ grd_files_debug_sources = [ "front_end/panels/explain/components/ConsoleInsight.js", "front_end/panels/explain/components/consoleInsight.css.js", "front_end/panels/explain/components/consoleInsightSourcesList.css.js", - "front_end/panels/freestyler/FreestylerAgent.js", - "front_end/panels/freestyler/FreestylerEvaluateAction.js", - "front_end/panels/freestyler/FreestylerPanel.js", - "front_end/panels/freestyler/components/FreestylerChatUi.js", - "front_end/panels/freestyler/components/ProvideFeedback.js", - "front_end/panels/freestyler/components/freestylerChatUi.css.js", - "front_end/panels/freestyler/components/provideFeedback.css.js", - "front_end/panels/freestyler/freestylerPanel.css.js", "front_end/panels/issues/AffectedBlockedByResponseView.js", "front_end/panels/issues/AffectedCookiesView.js", + "front_end/panels/issues/AffectedDescendantsWithinSelectElementView.js", "front_end/panels/issues/AffectedDirectivesView.js", "front_end/panels/issues/AffectedDocumentsInQuirksModeView.js", "front_end/panels/issues/AffectedElementsView.js", "front_end/panels/issues/AffectedElementsWithLowContrastView.js", "front_end/panels/issues/AffectedHeavyAdView.js", "front_end/panels/issues/AffectedMetadataAllowedSitesView.js", + "front_end/panels/issues/AffectedPartitioningBlobURLView.js", "front_end/panels/issues/AffectedResourcesView.js", "front_end/panels/issues/AffectedSharedArrayBufferIssueDetailsView.js", "front_end/panels/issues/AffectedSourcesView.js", @@ -1416,6 +1563,7 @@ grd_files_debug_sources = [ "front_end/panels/layer_viewer/PaintProfilerView.js", "front_end/panels/layer_viewer/TransformController.js", "front_end/panels/layer_viewer/layerDetailsView.css.js", + "front_end/panels/layer_viewer/layerTreeOutline.css.js", "front_end/panels/layer_viewer/layers3DView.css.js", "front_end/panels/layer_viewer/paintProfiler.css.js", "front_end/panels/layers/LayerPaintProfilerView.js", @@ -1467,6 +1615,7 @@ grd_files_debug_sources = [ "front_end/panels/media/playerListView.css.js", "front_end/panels/media/playerMessagesView.css.js", "front_end/panels/media/playerPropertiesView.css.js", + "front_end/panels/mobile_throttling/CalibrationController.js", "front_end/panels/mobile_throttling/MobileThrottlingSelector.js", "front_end/panels/mobile_throttling/NetworkPanelIndicator.js", "front_end/panels/mobile_throttling/NetworkThrottlingSelector.js", @@ -1538,6 +1687,8 @@ grd_files_debug_sources = [ "front_end/panels/performance_monitor/performanceMonitor.css.js", "front_end/panels/profiler/BottomUpProfileDataGrid.js", "front_end/panels/profiler/ChildrenProvider.js", + "front_end/panels/profiler/HeapDetachedElementsDataGrid.js", + "front_end/panels/profiler/HeapDetachedElementsView.js", "front_end/panels/profiler/HeapProfileView.js", "front_end/panels/profiler/HeapProfilerPanel.js", "front_end/panels/profiler/HeapSnapshotDataGrids.js", @@ -1562,11 +1713,9 @@ grd_files_debug_sources = [ "front_end/panels/profiler/profileLauncherView.css.js", "front_end/panels/profiler/profilesPanel.css.js", "front_end/panels/profiler/profilesSidebarTree.css.js", + "front_end/panels/protocol_monitor/JSONEditor.css.js", + "front_end/panels/protocol_monitor/JSONEditor.js", "front_end/panels/protocol_monitor/ProtocolMonitor.js", - "front_end/panels/protocol_monitor/components/JSONEditor.css.js", - "front_end/panels/protocol_monitor/components/JSONEditor.js", - "front_end/panels/protocol_monitor/components/Toolbar.js", - "front_end/panels/protocol_monitor/components/toolbar.css.js", "front_end/panels/protocol_monitor/protocolMonitor.css.js", "front_end/panels/react_devtools/ReactDevToolsComponentsView.js", "front_end/panels/react_devtools/ReactDevToolsModel.js", @@ -1582,7 +1731,6 @@ grd_files_debug_sources = [ "front_end/panels/recorder/components/RecordingView.js", "front_end/panels/recorder/components/ReplaySection.js", "front_end/panels/recorder/components/SelectButton.js", - "front_end/panels/recorder/components/StartView.js", "front_end/panels/recorder/components/StepEditor.js", "front_end/panels/recorder/components/StepView.js", "front_end/panels/recorder/components/TimelineSection.js", @@ -1592,7 +1740,6 @@ grd_files_debug_sources = [ "front_end/panels/recorder/components/recordingListView.css.js", "front_end/panels/recorder/components/recordingView.css.js", "front_end/panels/recorder/components/selectButton.css.js", - "front_end/panels/recorder/components/startView.css.js", "front_end/panels/recorder/components/stepEditor.css.js", "front_end/panels/recorder/components/stepView.css.js", "front_end/panels/recorder/components/timelineSection.css.js", @@ -1603,6 +1750,7 @@ grd_files_debug_sources = [ "front_end/panels/recorder/converters/JSONConverter.js", "front_end/panels/recorder/converters/LighthouseConverter.js", "front_end/panels/recorder/converters/PuppeteerConverter.js", + "front_end/panels/recorder/converters/PuppeteerFirefoxConverter.js", "front_end/panels/recorder/converters/PuppeteerReplayConverter.js", "front_end/panels/recorder/extensions/ExtensionManager.js", "front_end/panels/recorder/injected/Logger.js", @@ -1645,8 +1793,17 @@ grd_files_debug_sources = [ "front_end/panels/search/SearchView.js", "front_end/panels/search/searchResultsPane.css.js", "front_end/panels/search/searchView.css.js", + "front_end/panels/security/CookieControlsTreeElement.js", + "front_end/panels/security/CookieControlsView.js", + "front_end/panels/security/CookieReportTreeElement.js", + "front_end/panels/security/CookieReportView.js", + "front_end/panels/security/OriginTreeElement.js", "front_end/panels/security/SecurityModel.js", "front_end/panels/security/SecurityPanel.js", + "front_end/panels/security/SecurityPanelSidebar.js", + "front_end/panels/security/SecurityPanelSidebarTreeElement.js", + "front_end/panels/security/cookieControlsView.css.js", + "front_end/panels/security/cookieReportView.css.js", "front_end/panels/security/lockIcon.css.js", "front_end/panels/security/mainView.css.js", "front_end/panels/security/originView.css.js", @@ -1655,9 +1812,11 @@ grd_files_debug_sources = [ "front_end/panels/sensors/SensorsView.js", "front_end/panels/sensors/locationsSettingsTab.css.js", "front_end/panels/sensors/sensors.css.js", + "front_end/panels/settings/AISettingsTab.js", "front_end/panels/settings/FrameworkIgnoreListSettingsTab.js", "front_end/panels/settings/KeybindsSettingsTab.js", "front_end/panels/settings/SettingsScreen.js", + "front_end/panels/settings/aiSettingsTab.css.js", "front_end/panels/settings/components/SyncSection.js", "front_end/panels/settings/components/syncSection.css.js", "front_end/panels/settings/emulation/DevicesSettingsTab.js", @@ -1672,6 +1831,7 @@ grd_files_debug_sources = [ "front_end/panels/snippets/ScriptSnippetFileSystem.js", "front_end/panels/snippets/SnippetsQuickOpen.js", "front_end/panels/sources/AddSourceMapURLDialog.js", + "front_end/panels/sources/AiWarningInfobarPlugin.js", "front_end/panels/sources/BreakpointEditDialog.js", "front_end/panels/sources/CSSPlugin.js", "front_end/panels/sources/CallStackSidebarPane.js", @@ -1720,16 +1880,16 @@ grd_files_debug_sources = [ "front_end/panels/sources/watchExpressionsSidebarPane.css.js", "front_end/panels/timeline/ActiveFilters.js", "front_end/panels/timeline/AnimationsTrackAppender.js", + "front_end/panels/timeline/AnnotationHelpers.js", "front_end/panels/timeline/AppenderUtils.js", "front_end/panels/timeline/BenchmarkEvents.js", "front_end/panels/timeline/CLSLinkifier.js", "front_end/panels/timeline/CompatibilityTracksAppender.js", "front_end/panels/timeline/CountersGraph.js", "front_end/panels/timeline/EasterEgg.js", - "front_end/panels/timeline/EventUICategory.js", + "front_end/panels/timeline/EntriesFilter.js", "front_end/panels/timeline/EventsSerializer.js", "front_end/panels/timeline/EventsTimelineTreeView.js", - "front_end/panels/timeline/ExtensionDataGatherer.js", "front_end/panels/timeline/ExtensionTrackAppender.js", "front_end/panels/timeline/FreshRecording.js", "front_end/panels/timeline/GPUTrackAppender.js", @@ -1740,8 +1900,8 @@ grd_files_debug_sources = [ "front_end/panels/timeline/ModificationsManager.js", "front_end/panels/timeline/NetworkTrackAppender.js", "front_end/panels/timeline/SaveFileFormatter.js", - "front_end/panels/timeline/SourceMapsResolver.js", "front_end/panels/timeline/TargetForEvent.js", + "front_end/panels/timeline/ThirdPartyTreeView.js", "front_end/panels/timeline/ThreadAppender.js", "front_end/panels/timeline/TimelineController.js", "front_end/panels/timeline/TimelineDetailsView.js", @@ -1751,7 +1911,6 @@ grd_files_debug_sources = [ "front_end/panels/timeline/TimelineFlameChartNetworkDataProvider.js", "front_end/panels/timeline/TimelineFlameChartView.js", "front_end/panels/timeline/TimelineHistoryManager.js", - "front_end/panels/timeline/TimelineLandingPage.js", "front_end/panels/timeline/TimelineLayersView.js", "front_end/panels/timeline/TimelineLoader.js", "front_end/panels/timeline/TimelineMiniMap.js", @@ -1762,6 +1921,7 @@ grd_files_debug_sources = [ "front_end/panels/timeline/TimelineTreeView.js", "front_end/panels/timeline/TimelineUIUtils.js", "front_end/panels/timeline/TimingsTrackAppender.js", + "front_end/panels/timeline/TracingLayerTree.js", "front_end/panels/timeline/UIDevtoolsController.js", "front_end/panels/timeline/UIDevtoolsUtils.js", "front_end/panels/timeline/components/Breadcrumbs.js", @@ -1769,34 +1929,79 @@ grd_files_debug_sources = [ "front_end/panels/timeline/components/CPUThrottlingSelector.js", "front_end/panels/timeline/components/DetailsView.js", "front_end/panels/timeline/components/FieldSettingsDialog.js", + "front_end/panels/timeline/components/IgnoreListSetting.js", "front_end/panels/timeline/components/InteractionBreakdown.js", + "front_end/panels/timeline/components/LayoutShiftDetails.js", "front_end/panels/timeline/components/LiveMetricsView.js", + "front_end/panels/timeline/components/MetricCard.js", + "front_end/panels/timeline/components/MetricCompareStrings.js", "front_end/panels/timeline/components/NetworkRequestDetails.js", "front_end/panels/timeline/components/NetworkRequestTooltip.js", "front_end/panels/timeline/components/NetworkThrottlingSelector.js", + "front_end/panels/timeline/components/OriginMap.js", + "front_end/panels/timeline/components/RelatedInsightChips.js", "front_end/panels/timeline/components/Sidebar.js", "front_end/panels/timeline/components/SidebarAnnotationsTab.js", - "front_end/panels/timeline/components/SidebarSingleNavigation.js", + "front_end/panels/timeline/components/SidebarInsightsTab.js", + "front_end/panels/timeline/components/SidebarSingleInsightSet.js", + "front_end/panels/timeline/components/TimelineSummary.js", "front_end/panels/timeline/components/Utils.js", "front_end/panels/timeline/components/breadcrumbsUI.css.js", + "front_end/panels/timeline/components/cpuThrottlingSelector.css.js", "front_end/panels/timeline/components/fieldSettingsDialog.css.js", + "front_end/panels/timeline/components/ignoreListSetting.css.js", + "front_end/panels/timeline/components/insights/BaseInsightComponent.js", + "front_end/panels/timeline/components/insights/CLSCulprits.js", + "front_end/panels/timeline/components/insights/Cache.js", + "front_end/panels/timeline/components/insights/Checklist.js", + "front_end/panels/timeline/components/insights/DOMSize.js", + "front_end/panels/timeline/components/insights/DocumentLatency.js", + "front_end/panels/timeline/components/insights/DuplicatedJavaScript.js", + "front_end/panels/timeline/components/insights/EventRef.js", + "front_end/panels/timeline/components/insights/FontDisplay.js", + "front_end/panels/timeline/components/insights/ForcedReflow.js", + "front_end/panels/timeline/components/insights/Helpers.js", + "front_end/panels/timeline/components/insights/ImageDelivery.js", + "front_end/panels/timeline/components/insights/InteractionToNextPaint.js", + "front_end/panels/timeline/components/insights/LCPDiscovery.js", "front_end/panels/timeline/components/insights/LCPPhases.js", + "front_end/panels/timeline/components/insights/LegacyJavaScript.js", + "front_end/panels/timeline/components/insights/ModernHTTP.js", + "front_end/panels/timeline/components/insights/NetworkDependencyTree.js", + "front_end/panels/timeline/components/insights/NodeLink.js", + "front_end/panels/timeline/components/insights/RenderBlocking.js", + "front_end/panels/timeline/components/insights/ScriptRef.js", "front_end/panels/timeline/components/insights/SidebarInsight.js", - "front_end/panels/timeline/components/insights/sidebarInsight.css.js", + "front_end/panels/timeline/components/insights/SlowCSSSelector.js", + "front_end/panels/timeline/components/insights/Table.js", + "front_end/panels/timeline/components/insights/ThirdParties.js", + "front_end/panels/timeline/components/insights/Viewport.js", + "front_end/panels/timeline/components/insights/baseInsightComponent.css.js", + "front_end/panels/timeline/components/insights/checklist.css.js", + "front_end/panels/timeline/components/insights/networkDependencyTreeInsight.css.js", + "front_end/panels/timeline/components/insights/table.css.js", "front_end/panels/timeline/components/insights/types.js", "front_end/panels/timeline/components/interactionBreakdown.css.js", + "front_end/panels/timeline/components/layoutShiftDetails.css.js", "front_end/panels/timeline/components/liveMetricsView.css.js", + "front_end/panels/timeline/components/metricCard.css.js", + "front_end/panels/timeline/components/metricValueStyles.css.js", "front_end/panels/timeline/components/networkRequestDetails.css.js", "front_end/panels/timeline/components/networkRequestTooltip.css.js", - "front_end/panels/timeline/components/sidebar.css.js", + "front_end/panels/timeline/components/networkThrottlingSelector.css.js", + "front_end/panels/timeline/components/originMap.css.js", + "front_end/panels/timeline/components/relatedInsightChips.css.js", "front_end/panels/timeline/components/sidebarAnnotationsTab.css.js", - "front_end/panels/timeline/components/sidebarSingleNavigation.css.js", + "front_end/panels/timeline/components/sidebarInsightsTab.css.js", + "front_end/panels/timeline/components/sidebarSingleInsightSet.css.js", + "front_end/panels/timeline/components/timelineSummary.css.js", "front_end/panels/timeline/extensions/ExtensionUI.js", - "front_end/panels/timeline/historyToolbarButton.css.js", "front_end/panels/timeline/overlays/OverlaysImpl.js", + "front_end/panels/timeline/overlays/components/EntriesLinkOverlay.js", "front_end/panels/timeline/overlays/components/EntryLabelOverlay.js", "front_end/panels/timeline/overlays/components/TimeRangeOverlay.js", "front_end/panels/timeline/overlays/components/TimespanBreakdownOverlay.js", + "front_end/panels/timeline/overlays/components/entriesLinkOverlay.css.js", "front_end/panels/timeline/overlays/components/entryLabelOverlay.css.js", "front_end/panels/timeline/overlays/components/timeRangeOverlay.css.js", "front_end/panels/timeline/overlays/components/timespanBreakdownOverlay.css.js", @@ -1806,8 +2011,18 @@ grd_files_debug_sources = [ "front_end/panels/timeline/timelineMiniMap.css.js", "front_end/panels/timeline/timelinePaintProfiler.css.js", "front_end/panels/timeline/timelinePanel.css.js", + "front_end/panels/timeline/timelineSelectorStatsView.css.js", "front_end/panels/timeline/timelineStatusDialog.css.js", - "front_end/panels/timeline/utils/NetworkRequest.js", + "front_end/panels/timeline/utils/AICallTree.js", + "front_end/panels/timeline/utils/EntityMapper.js", + "front_end/panels/timeline/utils/EntryName.js", + "front_end/panels/timeline/utils/EntryStyles.js", + "front_end/panels/timeline/utils/Helpers.js", + "front_end/panels/timeline/utils/IgnoreList.js", + "front_end/panels/timeline/utils/ImageCache.js", + "front_end/panels/timeline/utils/InsightAIContext.js", + "front_end/panels/timeline/utils/SourceMapsResolver.js", + "front_end/panels/timeline/utils/Treemap.js", "front_end/panels/web_audio/AudioContextContentBuilder.js", "front_end/panels/web_audio/AudioContextSelector.js", "front_end/panels/web_audio/WebAudioModel.js", @@ -1822,6 +2037,10 @@ grd_files_debug_sources = [ "front_end/panels/web_audio/webAudio.css.js", "front_end/panels/webauthn/WebauthnPane.js", "front_end/panels/webauthn/webauthnPane.css.js", + "front_end/panels/whats_new/ReleaseNoteText.js", + "front_end/panels/whats_new/ReleaseNoteView.js", + "front_end/panels/whats_new/WhatsNewImpl.js", + "front_end/panels/whats_new/releaseNoteView.css.js", "front_end/services/puppeteer/PuppeteerConnection.js", "front_end/services/trace_bounds/TraceBounds.js", "front_end/services/tracing/PerformanceTracing.js", @@ -1849,12 +2068,16 @@ grd_files_debug_sources = [ "front_end/third_party/i18n/i18n-impl.js", "front_end/third_party/i18n/localized-string-set.js", "front_end/third_party/intl-messageformat/package/intl-messageformat.esm.js", + "front_end/third_party/json5/lib/index.js", + "front_end/third_party/json5/package/lib/index.js", + "front_end/third_party/legacy-javascript/lib/legacy-javascript.js", "front_end/third_party/lighthouse/report-assets/report-generator.mjs", "front_end/third_party/lighthouse/report/bundle.js", "front_end/third_party/lit/lib/decorators.js", "front_end/third_party/lit/lib/directive.js", "front_end/third_party/lit/lib/directives.js", "front_end/third_party/lit/lib/lit.js", + "front_end/third_party/lit/lib/static-html.js", "front_end/third_party/marked/package/lib/marked.esm.js", "front_end/third_party/puppeteer-replay/package/lib/main.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/api/Browser.js", @@ -1913,9 +2136,8 @@ grd_files_debug_sources = [ "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/Browser.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/BrowserConnector.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/BrowserContext.js", - "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/CDPSession.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/CdpPreloadScript.js", - "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/ChromeTargetManager.js", + "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/CdpSession.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/Connection.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/Coverage.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/DeviceRequestPrompt.js", @@ -1924,7 +2146,6 @@ grd_files_debug_sources = [ "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/EmulationManager.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/ExecutionContext.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/ExtensionTransport.js", - "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/FirefoxTargetManager.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/Frame.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/FrameManager.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/FrameManagerEvents.js", @@ -1941,6 +2162,7 @@ grd_files_debug_sources = [ "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/Page.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/PredefinedNetworkConditions.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/Target.js", + "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/TargetManageEvents.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/TargetManager.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/Tracing.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/cdp/WebWorker.js", @@ -1958,6 +2180,7 @@ grd_files_debug_sources = [ "front_end/third_party/puppeteer/package/lib/esm/puppeteer/common/CustomQueryHandler.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/common/Debug.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/common/Device.js", + "front_end/third_party/puppeteer/package/lib/esm/puppeteer/common/DownloadBehavior.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/common/Errors.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/common/EventEmitter.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/common/FileChooser.js", @@ -1969,11 +2192,11 @@ grd_files_debug_sources = [ "front_end/third_party/puppeteer/package/lib/esm/puppeteer/common/PQueryHandler.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/common/PSelectorParser.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/common/PierceQueryHandler.js", - "front_end/third_party/puppeteer/package/lib/esm/puppeteer/common/Product.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/common/Puppeteer.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/common/QueryHandler.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/common/ScriptInjector.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/common/SecurityDetails.js", + "front_end/third_party/puppeteer/package/lib/esm/puppeteer/common/SupportedBrowser.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/common/TaskQueue.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/common/TextQueryHandler.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/common/TimeoutSettings.js", @@ -2000,12 +2223,12 @@ grd_files_debug_sources = [ "front_end/third_party/puppeteer/package/lib/esm/puppeteer/injected/XPathQuerySelector.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/injected/injected.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/injected/util.js", + "front_end/third_party/puppeteer/package/lib/esm/puppeteer/node/BrowserLauncher.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/node/ChromeLauncher.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/node/FirefoxLauncher.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/node/LaunchOptions.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/node/NodeWebSocketTransport.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/node/PipeTransport.js", - "front_end/third_party/puppeteer/package/lib/esm/puppeteer/node/ProductLauncher.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/node/PuppeteerNode.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/node/ScreenRecorder.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/node/node.js", @@ -2021,6 +2244,8 @@ grd_files_debug_sources = [ "front_end/third_party/puppeteer/package/lib/esm/puppeteer/util/assert.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/util/decorators.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/util/disposable.js", + "front_end/third_party/puppeteer/package/lib/esm/puppeteer/util/encoding.js", + "front_end/third_party/puppeteer/package/lib/esm/puppeteer/util/incremental-id-generator.js", "front_end/third_party/puppeteer/package/lib/esm/puppeteer/util/util.js", "front_end/third_party/puppeteer/package/lib/esm/third_party/mitt/mitt.js", "front_end/third_party/puppeteer/package/lib/esm/third_party/parsel-js/parsel-js.js", @@ -2028,6 +2253,7 @@ grd_files_debug_sources = [ "front_end/third_party/react-devtools/package/frontend.css.js", "front_end/third_party/react-devtools/package/frontend.js", "front_end/third_party/react-devtools/package/importFile.worker.worker.js", + "front_end/third_party/third-party-web/lib/nostats-subset.js", "front_end/third_party/wasmparser/package/dist/esm/WasmDis.js", "front_end/third_party/wasmparser/package/dist/esm/WasmParser.js", "front_end/third_party/web-vitals/package/dist/modules/attribution/deprecated.js", @@ -2078,38 +2304,36 @@ grd_files_debug_sources = [ "front_end/ui/components/adorners/adorner.css.js", "front_end/ui/components/buttons/Button.js", "front_end/ui/components/buttons/button.css.js", + "front_end/ui/components/buttons/textButton.css.js", + "front_end/ui/components/cards/Card.js", + "front_end/ui/components/cards/card.css.js", "front_end/ui/components/chrome_link/ChromeLink.js", "front_end/ui/components/chrome_link/chromeLink.css.js", "front_end/ui/components/code_highlighter/CodeHighlighter.js", "front_end/ui/components/code_highlighter/codeHighlighter.css.js", - "front_end/ui/components/data_grid/DataGrid.js", - "front_end/ui/components/data_grid/DataGridContextMenuUtils.js", - "front_end/ui/components/data_grid/DataGridController.js", - "front_end/ui/components/data_grid/DataGridControllerIntegrator.js", - "front_end/ui/components/data_grid/DataGridEvents.js", - "front_end/ui/components/data_grid/DataGridRenderers.js", - "front_end/ui/components/data_grid/DataGridUtils.js", - "front_end/ui/components/data_grid/dataGrid.css.js", - "front_end/ui/components/data_grid/dataGridController.css.js", + "front_end/ui/components/dialogs/ButtonDialog.js", "front_end/ui/components/dialogs/Dialog.js", - "front_end/ui/components/dialogs/IconDialog.js", "front_end/ui/components/dialogs/ShortcutDialog.js", + "front_end/ui/components/dialogs/buttonDialog.css.js", "front_end/ui/components/dialogs/dialog.css.js", - "front_end/ui/components/dialogs/iconDialog.css.js", "front_end/ui/components/dialogs/shortcutDialog.css.js", "front_end/ui/components/diff_view/DiffView.js", "front_end/ui/components/diff_view/diffView.css.js", "front_end/ui/components/expandable_list/ExpandableList.js", "front_end/ui/components/expandable_list/expandableList.css.js", + "front_end/ui/components/floating_button/FloatingButton.js", + "front_end/ui/components/floating_button/floatingButton.css.js", "front_end/ui/components/helpers/component-server-setup.js", "front_end/ui/components/helpers/directives.js", "front_end/ui/components/helpers/get-root-node.js", "front_end/ui/components/helpers/scheduled-render.js", "front_end/ui/components/highlighting/HighlightManager.js", "front_end/ui/components/highlighting/highlighting.css.js", + "front_end/ui/components/icon_button/FileSourceIcon.js", "front_end/ui/components/icon_button/Icon.js", "front_end/ui/components/icon_button/IconButton.js", - "front_end/ui/components/icon_button/icon.css.legacy.js", + "front_end/ui/components/icon_button/fileSourceIcon.css.js", + "front_end/ui/components/icon_button/icon.css.js", "front_end/ui/components/icon_button/iconButton.css.js", "front_end/ui/components/input/checkbox.css.js", "front_end/ui/components/input/textInput.css.js", @@ -2147,7 +2371,6 @@ grd_files_debug_sources = [ "front_end/ui/components/panel_feedback/previewToggle.css.js", "front_end/ui/components/panel_introduction_steps/PanelIntroductionSteps.js", "front_end/ui/components/panel_introduction_steps/panelIntroductionSteps.css.js", - "front_end/ui/components/render_coordinator/RenderCoordinator.js", "front_end/ui/components/report_view/ReportView.js", "front_end/ui/components/report_view/report.css.js", "front_end/ui/components/report_view/reportKey.css.js", @@ -2161,13 +2384,16 @@ grd_files_debug_sources = [ "front_end/ui/components/settings/SettingDeprecationWarning.js", "front_end/ui/components/settings/settingCheckbox.css.js", "front_end/ui/components/settings/settingDeprecationWarning.css.js", - "front_end/ui/components/split_view/SplitView.js", + "front_end/ui/components/spinners/Spinner.js", + "front_end/ui/components/spinners/spinner.css.js", "front_end/ui/components/srgb_overlay/SrgbOverlay.js", "front_end/ui/components/srgb_overlay/srgbOverlay.css.js", "front_end/ui/components/suggestion_input/SuggestionInput.js", "front_end/ui/components/suggestion_input/suggestionInput.css.js", "front_end/ui/components/survey_link/SurveyLink.js", "front_end/ui/components/survey_link/surveyLink.css.js", + "front_end/ui/components/switch/SwitchImpl.js", + "front_end/ui/components/switch/switch.css.js", "front_end/ui/components/text_editor/AutocompleteHistory.js", "front_end/ui/components/text_editor/ExecutionPositionHighlighter.js", "front_end/ui/components/text_editor/TextEditor.js", @@ -2179,11 +2405,11 @@ grd_files_debug_sources = [ "front_end/ui/components/text_editor/theme.js", "front_end/ui/components/text_prompt/TextPrompt.js", "front_end/ui/components/text_prompt/textPrompt.css.js", + "front_end/ui/components/tooltips/Tooltip.js", + "front_end/ui/components/tooltips/tooltip.css.js", "front_end/ui/components/tree_outline/TreeOutline.js", "front_end/ui/components/tree_outline/TreeOutlineUtils.js", "front_end/ui/components/tree_outline/treeOutline.css.js", - "front_end/ui/components/two_states_counter/TwoStatesCounter.js", - "front_end/ui/components/two_states_counter/twoStatesCounter.css.js", "front_end/ui/legacy/ARIAUtils.js", "front_end/ui/legacy/ActionRegistration.js", "front_end/ui/legacy/ActionRegistry.js", @@ -2200,7 +2426,6 @@ grd_files_debug_sources = [ "front_end/ui/legacy/Fragment.js", "front_end/ui/legacy/Geometry.js", "front_end/ui/legacy/GlassPane.js", - "front_end/ui/legacy/HistoryInput.js", "front_end/ui/legacy/Infobar.js", "front_end/ui/legacy/InplaceEditor.js", "front_end/ui/legacy/InspectorView.js", @@ -2238,8 +2463,7 @@ grd_files_debug_sources = [ "front_end/ui/legacy/XLink.js", "front_end/ui/legacy/XWidget.js", "front_end/ui/legacy/ZoomManager.js", - "front_end/ui/legacy/applicationColorTokens.css.legacy.js", - "front_end/ui/legacy/checkboxTextLabel.css.legacy.js", + "front_end/ui/legacy/checkboxTextLabel.css.js", "front_end/ui/legacy/components/color_picker/ColorFormatSpec.js", "front_end/ui/legacy/components/color_picker/ContrastDetails.js", "front_end/ui/legacy/components/color_picker/ContrastInfo.js", @@ -2250,6 +2474,7 @@ grd_files_debug_sources = [ "front_end/ui/legacy/components/cookie_table/CookiesTable.js", "front_end/ui/legacy/components/cookie_table/cookiesTable.css.js", "front_end/ui/legacy/components/data_grid/DataGrid.js", + "front_end/ui/legacy/components/data_grid/DataGridElement.js", "front_end/ui/legacy/components/data_grid/ShowMoreDataGridNode.js", "front_end/ui/legacy/components/data_grid/SortableDataGrid.js", "front_end/ui/legacy/components/data_grid/ViewportDataGrid.js", @@ -2262,8 +2487,6 @@ grd_files_debug_sources = [ "front_end/ui/legacy/components/inline_editor/CSSAngleEditor.js", "front_end/ui/legacy/components/inline_editor/CSSAngleSwatch.js", "front_end/ui/legacy/components/inline_editor/CSSAngleUtils.js", - "front_end/ui/legacy/components/inline_editor/CSSLength.js", - "front_end/ui/legacy/components/inline_editor/CSSLengthUtils.js", "front_end/ui/legacy/components/inline_editor/CSSLinearEasingModel.js", "front_end/ui/legacy/components/inline_editor/CSSShadowEditor.js", "front_end/ui/legacy/components/inline_editor/ColorMixSwatch.js", @@ -2282,7 +2505,6 @@ grd_files_debug_sources = [ "front_end/ui/legacy/components/inline_editor/cssAngle.css.js", "front_end/ui/legacy/components/inline_editor/cssAngleEditor.css.js", "front_end/ui/legacy/components/inline_editor/cssAngleSwatch.css.js", - "front_end/ui/legacy/components/inline_editor/cssLength.css.js", "front_end/ui/legacy/components/inline_editor/cssShadowEditor.css.js", "front_end/ui/legacy/components/inline_editor/cssShadowSwatch.css.js", "front_end/ui/legacy/components/inline_editor/fontEditor.css.js", @@ -2312,12 +2534,12 @@ grd_files_debug_sources = [ "front_end/ui/legacy/components/perf_ui/TimelineGrid.js", "front_end/ui/legacy/components/perf_ui/TimelineOverviewCalculator.js", "front_end/ui/legacy/components/perf_ui/TimelineOverviewPane.js", - "front_end/ui/legacy/components/perf_ui/chartViewport.css.legacy.js", - "front_end/ui/legacy/components/perf_ui/filmStripView.css.legacy.js", - "front_end/ui/legacy/components/perf_ui/flameChart.css.legacy.js", - "front_end/ui/legacy/components/perf_ui/overviewGrid.css.legacy.js", + "front_end/ui/legacy/components/perf_ui/chartViewport.css.js", + "front_end/ui/legacy/components/perf_ui/filmStripView.css.js", + "front_end/ui/legacy/components/perf_ui/flameChart.css.js", + "front_end/ui/legacy/components/perf_ui/overviewGrid.css.js", "front_end/ui/legacy/components/perf_ui/pieChart.css.js", - "front_end/ui/legacy/components/perf_ui/timelineGrid.css.legacy.js", + "front_end/ui/legacy/components/perf_ui/timelineGrid.css.js", "front_end/ui/legacy/components/perf_ui/timelineOverviewInfo.css.js", "front_end/ui/legacy/components/quick_open/CommandMenu.js", "front_end/ui/legacy/components/quick_open/FilteredListWidget.js", @@ -2331,14 +2553,14 @@ grd_files_debug_sources = [ "front_end/ui/legacy/components/source_frame/PreviewFactory.js", "front_end/ui/legacy/components/source_frame/ResourceSourceFrame.js", "front_end/ui/legacy/components/source_frame/SourceFrame.js", + "front_end/ui/legacy/components/source_frame/StreamingContentHexView.js", "front_end/ui/legacy/components/source_frame/XMLView.js", - "front_end/ui/legacy/components/source_frame/fontView.css.legacy.js", - "front_end/ui/legacy/components/source_frame/imageView.css.legacy.js", - "front_end/ui/legacy/components/source_frame/jsonView.css.legacy.js", - "front_end/ui/legacy/components/source_frame/resourceSourceFrame.css.legacy.js", - "front_end/ui/legacy/components/source_frame/selfXssDialog.css.legacy.js", - "front_end/ui/legacy/components/source_frame/xmlTree.css.legacy.js", - "front_end/ui/legacy/components/source_frame/xmlView.css.legacy.js", + "front_end/ui/legacy/components/source_frame/fontView.css.js", + "front_end/ui/legacy/components/source_frame/imageView.css.js", + "front_end/ui/legacy/components/source_frame/jsonView.css.js", + "front_end/ui/legacy/components/source_frame/resourceSourceFrame.css.js", + "front_end/ui/legacy/components/source_frame/xmlTree.css.js", + "front_end/ui/legacy/components/source_frame/xmlView.css.js", "front_end/ui/legacy/components/utils/ImagePreview.js", "front_end/ui/legacy/components/utils/JSPresentationUtils.js", "front_end/ui/legacy/components/utils/Linkifier.js", @@ -2346,48 +2568,40 @@ grd_files_debug_sources = [ "front_end/ui/legacy/components/utils/TargetDetachedDialog.js", "front_end/ui/legacy/components/utils/imagePreview.css.js", "front_end/ui/legacy/components/utils/jsUtils.css.js", - "front_end/ui/legacy/confirmDialog.css.legacy.js", - "front_end/ui/legacy/designTokens.css.legacy.js", - "front_end/ui/legacy/dialog.css.legacy.js", - "front_end/ui/legacy/dropTarget.css.legacy.js", + "front_end/ui/legacy/confirmDialog.css.js", + "front_end/ui/legacy/dialog.css.js", + "front_end/ui/legacy/dropTarget.css.js", "front_end/ui/legacy/emptyWidget.css.js", - "front_end/ui/legacy/emptyWidget.css.legacy.js", - "front_end/ui/legacy/filter.css.legacy.js", - "front_end/ui/legacy/glassPane.css.legacy.js", - "front_end/ui/legacy/infobar.css.legacy.js", - "front_end/ui/legacy/inlineButton.css.legacy.js", + "front_end/ui/legacy/filter.css.js", + "front_end/ui/legacy/glassPane.css.js", + "front_end/ui/legacy/infobar.css.js", + "front_end/ui/legacy/inlineButton.css.js", "front_end/ui/legacy/inspectorCommon.css.js", - "front_end/ui/legacy/inspectorCommon.css.legacy.js", - "front_end/ui/legacy/inspectorSyntaxHighlight.css.legacy.js", - "front_end/ui/legacy/inspectorViewTabbedPane.css.legacy.js", - "front_end/ui/legacy/listWidget.css.legacy.js", - "front_end/ui/legacy/popover.css.legacy.js", - "front_end/ui/legacy/progressIndicator.css.legacy.js", - "front_end/ui/legacy/radioButton.css.legacy.js", + "front_end/ui/legacy/inspectorViewTabbedPane.css.js", + "front_end/ui/legacy/listWidget.css.js", + "front_end/ui/legacy/popover.css.js", + "front_end/ui/legacy/progressIndicator.css.js", "front_end/ui/legacy/remoteDebuggingTerminatedScreen.css.js", - "front_end/ui/legacy/reportView.css.legacy.js", - "front_end/ui/legacy/rootView.css.legacy.js", - "front_end/ui/legacy/searchableView.css.legacy.js", - "front_end/ui/legacy/slider.css.legacy.js", - "front_end/ui/legacy/smallBubble.css.legacy.js", - "front_end/ui/legacy/softContextMenu.css.legacy.js", - "front_end/ui/legacy/softDropDown.css.legacy.js", - "front_end/ui/legacy/softDropDownButton.css.legacy.js", - "front_end/ui/legacy/splitWidget.css.legacy.js", - "front_end/ui/legacy/suggestBox.css.legacy.js", - "front_end/ui/legacy/tabbedPane.css.legacy.js", - "front_end/ui/legacy/targetCrashedScreen.css.legacy.js", - "front_end/ui/legacy/textButton.css.legacy.js", - "front_end/ui/legacy/textPrompt.css.legacy.js", - "front_end/ui/legacy/themeColors.css.legacy.js", + "front_end/ui/legacy/reportView.css.js", + "front_end/ui/legacy/rootView.css.js", + "front_end/ui/legacy/searchableView.css.js", + "front_end/ui/legacy/smallBubble.css.js", + "front_end/ui/legacy/softContextMenu.css.js", + "front_end/ui/legacy/softDropDown.css.js", + "front_end/ui/legacy/softDropDownButton.css.js", + "front_end/ui/legacy/splitWidget.css.js", + "front_end/ui/legacy/suggestBox.css.js", + "front_end/ui/legacy/tabbedPane.css.js", + "front_end/ui/legacy/targetCrashedScreen.css.js", + "front_end/ui/legacy/textPrompt.css.js", "front_end/ui/legacy/theme_support/ThemeSupport.js", - "front_end/ui/legacy/tokens.css.legacy.js", - "front_end/ui/legacy/toolbar.css.legacy.js", - "front_end/ui/legacy/treeoutline.css.legacy.js", - "front_end/ui/legacy/viewContainers.css.legacy.js", - "front_end/ui/lit-html/static.js", + "front_end/ui/legacy/toolbar.css.js", + "front_end/ui/legacy/treeoutline.css.js", + "front_end/ui/legacy/viewContainers.css.js", + "front_end/ui/lit/i18n-template.js", "front_end/ui/visual_logging/Debugging.js", "front_end/ui/visual_logging/DomState.js", + "front_end/ui/visual_logging/KnownContextValues.js", "front_end/ui/visual_logging/Loggable.js", "front_end/ui/visual_logging/LoggingConfig.js", "front_end/ui/visual_logging/LoggingDriver.js", diff --git a/config/gni/devtools_image_files.gni b/config/gni/devtools_image_files.gni index 076e5c9fdefa..261cf0870c72 100644 --- a/config/gni/devtools_image_files.gni +++ b/config/gni/devtools_image_files.gni @@ -23,7 +23,6 @@ devtools_image_files = [ "toolbarResizerVertical.png", "touchCursor_2x.png", "touchCursor.png", - "whatsnew.avif", ] devtools_svg_sources = [ @@ -32,6 +31,7 @@ devtools_svg_sources = [ "3d-rotate.svg", "accelerometer-back.svg", "accelerometer-front.svg", + "account-tree.svg", "align-content-center.svg", "align-content-end.svg", "align-content-space-around.svg", @@ -48,11 +48,15 @@ devtools_svg_sources = [ "align-self-end.svg", "align-self-start.svg", "align-self-stretch.svg", + "animation.svg", "arrow-back.svg", + "arrow-collapse.svg", "arrow-down.svg", "arrow-drop-down-dark.svg", "arrow-drop-down-light.svg", + "arrow-drop-down.svg", "arrow-forward.svg", + "arrow-right-circle.svg", "arrow-up-down-circle.svg", "arrow-up-down.svg", "arrow-up.svg", @@ -65,10 +69,14 @@ devtools_svg_sources = [ "breakpoint-circle.svg", "breakpoint-crossed-filled.svg", "breakpoint-crossed.svg", + "brush-2.svg", "brush-filled.svg", "brush.svg", "bug.svg", "bundle.svg", + "button-magic.svg", + "calendar-today.svg", + "center-focus-weak.svg", "check-circle.svg", "check-double.svg", "checker.svg", @@ -79,6 +87,7 @@ devtools_svg_sources = [ "chevron-left.svg", "chevron-right.svg", "chevron-up.svg", + "class.svg", "clear-list.svg", "clear.svg", "cloud.svg", @@ -87,10 +96,13 @@ devtools_svg_sources = [ "colon.svg", "color-picker-filled.svg", "color-picker.svg", + "compress.svg", "console-conditional-breakpoint.svg", "console-logpoint.svg", "cookie.svg", + "cookie_off.svg", "copy.svg", + "corporate-fare.svg", "credit-card.svg", "cross-circle-filled.svg", "cross-circle.svg", @@ -100,13 +112,17 @@ devtools_svg_sources = [ "deployed.svg", "device-fold.svg", "devices.svg", + "devtools-thumbnail.svg", + "devtools-tips.svg", "devtools.svg", + "difference.svg", "dock-bottom.svg", "dock-left.svg", "dock-right.svg", "dock-window.svg", "document.svg", "dog-paw.svg", + "domain.svg", "dots-horizontal.svg", "dots-vertical.svg", "download.svg", @@ -146,10 +162,17 @@ devtools_svg_sources = [ "gear-filled.svg", "gear.svg", "gears.svg", + "global.svg", + "google.svg", "goto-filled.svg", + "grid-on.svg", + "group.svg", "heap-snapshot.svg", "heap-snapshots.svg", "help.svg", + "history.svg", + "home.svg", + "hover.svg", "iframe-crossed.svg", "iframe.svg", "import.svg", @@ -171,14 +194,17 @@ devtools_svg_sources = [ "justify-items-start.svg", "justify-items-stretch.svg", "keyboard-arrow-right.svg", + "keyboard-full.svg", "keyboard-pen.svg", "keyboard.svg", + "label.svg", "large-arrow-right-filled.svg", "layers-filled.svg", "layers.svg", "left-panel-close.svg", "left-panel-open.svg", "lightbulb-spark.svg", + "lightbulb.svg", "lighthouse_logo.svg", "list.svg", "location-on.svg", @@ -190,15 +216,27 @@ devtools_svg_sources = [ "mop.svg", "mouse.svg", "network-settings.svg", + "node-stack-icon.svg", "open-externally.svg", + "override.svg", + "palette.svg", + "pause-circle.svg", "pause.svg", + "pen-spark.svg", + "performance-panel-delete-annotation.svg", + "performance-panel-diagram.svg", + "performance-panel-entry-label.svg", + "performance-panel-time-range.svg", "performance.svg", "person.svg", + "photo-camera.svg", "play.svg", "plus.svg", + "policy.svg", "popup.svg", "preview_feature_video_thumbnail.svg", "profile.svg", + "psychiatry.svg", "record-start.svg", "record-stop.svg", "redo.svg", @@ -221,9 +259,9 @@ devtools_svg_sources = [ "send.svg", "shadow.svg", "small-status-dot.svg", + "smart-assistant.svg", "snippet.svg", "spark-info.svg", - "spark.svg", "star.svg", "step-into.svg", "step-out.svg", @@ -233,8 +271,12 @@ devtools_svg_sources = [ "symbol.svg", "sync.svg", "table.svg", + "terminal.svg", + "thumb-down-filled.svg", "thumb-down.svg", + "thumb-up-filled.svg", "thumb-up.svg", + "tonality.svg", "top-panel-close.svg", "top-panel-open.svg", "touch-app.svg", @@ -243,10 +285,12 @@ devtools_svg_sources = [ "triangle-left.svg", "triangle-right.svg", "triangle-up.svg", + "tune.svg", "undo.svg", "warning-filled.svg", "warning.svg", "watch.svg", + "whatsnew.svg", "width.svg", "zoom-in.svg", ] diff --git a/config/owner/COMMON_OWNERS b/config/owner/COMMON_OWNERS index ca7d5d2643f7..b41493c3c368 100644 --- a/config/owner/COMMON_OWNERS +++ b/config/owner/COMMON_OWNERS @@ -1,15 +1,16 @@ file://config/owner/ENG_REVIEW_OWNERS +aixba@chromium.org alexrudenko@chromium.org alinavarkki@chromium.org andoli@chromium.org +asraine@chromium.org bmeurer@chromium.org changhaohan@chromium.org +cjamcl@chromium.org dsv@chromium.org ergunsh@chromium.org jacktfranklin@chromium.org -jarin@chromium.org -jrandolf@chromium.org kimanh@chromium.org kprokopenko@chromium.org leese@chromium.org @@ -21,6 +22,7 @@ paulirish@chromium.org petermueller@chromium.org pfaffe@chromium.org sadym@chromium.org +samiyac@chromium.org szuend@chromium.org victorporof@chromium.org wolfi@chromium.org diff --git a/config/owner/ENG_REVIEW_OWNERS b/config/owner/ENG_REVIEW_OWNERS index 46d4f05a3b8c..20189aad0a14 100644 --- a/config/owner/ENG_REVIEW_OWNERS +++ b/config/owner/ENG_REVIEW_OWNERS @@ -1,3 +1,7 @@ +addyo@chromium.org bmeurer@chromium.org danno@chromium.org +mathias@chromium.org +paulirish@chromium.org +victorporof@chromium.org yangguo@chromium.org diff --git a/config/owner/INFRA_OWNERS b/config/owner/INFRA_OWNERS index fd2bf123019f..ba83763c5311 100644 --- a/config/owner/INFRA_OWNERS +++ b/config/owner/INFRA_OWNERS @@ -4,4 +4,5 @@ jacktfranklin@chromium.org liviurau@chromium.org machenbach@chromium.org mathias@chromium.org +paulirish@chromium.org szuend@chromium.org diff --git a/config/owner/RECORDER_OWNERS b/config/owner/RECORDER_OWNERS index 07058c5998fd..cfa2d44aec7f 100644 --- a/config/owner/RECORDER_OWNERS +++ b/config/owner/RECORDER_OWNERS @@ -1,3 +1,2 @@ alexrudenko@chromium.org -jrandolf@chromium.org nvitkov@chromium.org \ No newline at end of file diff --git a/config/typescript/tsconfig.eslint.json b/config/typescript/tsconfig.eslint.json index f82fd225e385..3799c075048c 100644 --- a/config/typescript/tsconfig.eslint.json +++ b/config/typescript/tsconfig.eslint.json @@ -1,19 +1,15 @@ { "extends": "./tsconfig.base.json", "compilerOptions": { - "lib": [ - "esnext", - "dom", - "dom.iterable", - "webworker", - "webworker.iterable" - ], + "lib": ["esnext", "dom", "dom.iterable", "webworker", "webworker.iterable"], "outDir": "ignored-for-vscode" }, "include": [ "../../front_end/**/*.ts", "../../inspector_overlay/**/*.ts", - "../../scripts/protocol_typescript/*.ts", - "../../test/**/*.ts" + "../../scripts/**/*.ts", + "../../test/**/*.ts", + "../../extensions/**/*.ts", + "../../extension-api/**/*.ts" ] } diff --git a/docs/README.md b/docs/README.md index 3e34f587087d..5beb046e4c31 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,5 +1,7 @@ # Chromium DevTools docs +[goo.gle/chromium-devtools](http://goo.gle/chromium-devtools) + This directory contains [Chrome DevTools] project documentation in [Gitiles-flavored Markdown]. It is automatically [rendered by Gitiles]. @@ -13,39 +15,54 @@ below.** [TOC] +## Work With Us + +* See the [playbook](./playbook.md) for step-by-step instructions on how to + work with Chromium DevTools to implement your idea. +* See the [Ecosystem Guide](./ecosystem/README.md) if you are working on Web + development tools and services, and would like to learn more about + integration and extension points with Chromium DevTools. + ## Document Index ### Design Documents + * See the shared [Design Documents](https://drive.google.com/drive/folders/1JbUthATfybvMQR3yAHC4J0P7n6oftYNq) folder in the Chromium drive. ### General Development -* [Get the Code](get_the_code.md) -* [Contributing Changes](contributing_changes.md) -* [Chrome DevTools Design Review Guidelines](design_guidelines.md) -* [Release Management](release_management.md) -* [Dependencies](dependencies.md) -* [Localization](l10n.md) -* [Material 3 in DevTools](material3_guidelines.md) -* [V8 debugger support checklist for new language features](https://goo.gle/v8-checklist) -* [Chrome DevTools Protocol](devtools-protocol.md) -* [Visual logging in DevTools](visual_logging.md) -* [UMA metrics in DevTools](uma_metrics.md) - * [How to add UMA metrics in DevTools frontend](add_uma_metrics.md) -* [How to add experiments in DevTools frontend](add_experiments.md) - -### Testing -* [Testing Chromium DevTools](testing.md) -* [E2E test guide](../test/e2e/README.md) -* [Unit test guide](unit_testing.md) + +* [Get the Code](./get_the_code.md) +* [Contribution Guide](./contributing/README.md) +* [UX Style Guide](./styleguide/ux/README.md) +* [Testing Guide](../test/README.md) +* [Cookbook](./cookbook/README.md) +* [Visual logging in DevTools](../front_end/ui/visual_logging/README.md) +* [Style Guides](./styleguide/README.md) ### Architectural Documentation + * [Architecture of DevTools](architecture_of_devtools.md) +* [Chrome DevTools Protocol (CDP)](devtools-protocol.md) * [Resource management in DevTools](resource_management.md) +* [UI Engineering](ui_engineering.md) ### Chromium -* [Chromium Docs](https://chromium.googlesource.com/chromium/src/+/master/docs/README.md) + +* [Chromium Docs](https://chromium.googlesource.com/chromium/src/+/main/docs/README.md) * [V8 Documention](https://v8.dev/docs) +### Checklists + +* [DevTools UI feature checklist](./checklist/ui.md) +* [DevTools support checklist for Blink Intents](./checklist/README.md) +* [DevTools support checklist for JavaScript features](./checklist/javascript.md) +* [DevTools support checklist for WebAssembly features](./checklist/webassembly.md) + +### Policies + +* [Chromium DevTools Slow-Close Policy](./policy/slow-close.md) +* [DevTools Page Zoom Accessibility Policy](./policy/gar-page-zoom-policy.md) + ### Useful Commands `git cl format --js` diff --git a/docs/add_experiments.md b/docs/add_experiments.md deleted file mode 100644 index e212f0622286..000000000000 --- a/docs/add_experiments.md +++ /dev/null @@ -1,77 +0,0 @@ -# How to add experiments in DevTools frontend - -If you want to launch a new feature in DevTools behind an experiment flag, you -will need to do two things: - -1. Make Chromium aware of the experiment and enable it to track users - enabling/disabling the experiment. -2. Register the experiment in DevTools to have it added to the Settings UI. - -[TOC] - -## Chromium - -In Chromium, edit `tools/metrics/histograms/enums.xml`. Find the enum titled -`DevToolsExperiments` (your best bet is to search for this text in your editor, -as `enums.xml` is very large). - -Go to the end of this enum, and add a new entry. Make sure that the `value` is -increased by one from the previous entry. The label can be anything you like but -make sure it is easily identifiable. - -```xml - -``` - -[See an example Chromium CL here](https://crrev.com/c/4915777). - -## DevTools frontend - -In DevTools, you need to register the experiment. This is done in -`front_end/entrypoints/main/MainImpl.ts` and is done by calling -`Root.Runtime.experiments.register`: - -```ts -Root.Runtime.experiments.register( - 'yourExperimentNameHere', - 'User facing short description of experiment here', - false); -``` - -The first argument is the experiment's label, and **this must match the label -you used in your Chromium CL**. - -The second argument is a short description of the experiment. This string will -be shown to users. - -Finally, the third argument marks the experiment as unstable. You should pass -`true` if you want your experiment to be marked as unstable. This moves it into -a separate part of the UI where users are warned that enabling the experiment -may cause issues. - -You may also pass in two additional arguments which can be used to link users to -documentation and a way to provide feedback: - -```ts -Root.Runtime.experiments.register( - 'jsProfilerTemporarilyEnable', - 'Enable JavaScript Profiler temporarily', - /* unstable= */ false, - /* documentation */ 'https://goo.gle/js-profiler-deprecation', - /* feedback */ 'https://crbug.com/1354548' -); -``` - -You must also add the experiment to `front_end/core/host/UserMetrics.ts`. Add an -entry to the `DevToolsExperiments` enum, using **the same label and integer -value** that you used in the Chromium CL. You should also increase the -`MaxValue` entry by one. - -Once the experiment is registered, you can check if it is enabled and use this -to run certain code blocks conditionally: - -```ts -if(Root.Runtime.experiments.isEnabled('yourExperimentNameHere')) { - // Experiment code here -} -``` diff --git a/docs/add_uma_metrics.md b/docs/add_uma_metrics.md deleted file mode 100644 index e1d9a1ad4ca3..000000000000 --- a/docs/add_uma_metrics.md +++ /dev/null @@ -1,41 +0,0 @@ -# How to add UMA metrics in DevTools frontend - -Decide on the metric (an [enumerated histogram](https://chromium.googlesource.com/chromium/src/tools/+/HEAD/metrics/histograms/README.md#enum-histograms) or an [action](https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/core/host/UserMetrics.ts;l=380) to be logged to generic `DevTools.ActionTaken` histogram) - -1. For enumerated histogram (We use this when there are multiple related states that should be analyzed jointly. For example, we might want to know the source of an action like where it is performed from) - 1. Choose a name for the new histogram prefixed with `DevTools`, for example, `DevTools.ColorPickerOpenedFrom`. - 2. Decide on the values for the different enums you want to log, for example, `StylesPane` and `SourcesPanel` for `DevTools.ColorPickerOpenedFrom` histogram. -2. For actions - 1. Decide on the name of the action, for example, `DeviceModeEnabled`. - -## Tracking an enumerated histogram - -1. Implement metric collection in devtools-frontend and create a CL. (Example [CL](https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/3998783)) - 1. Add the new histogram name to the [EnumeratedHistogram](https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/core/host/InspectorFrontendHostAPI.ts;l=351?q=InspectorFrontendHostAPI.ts) enum. - 2. Add the same histogram name to the EnumeratedHistogram object in [devtools_compatibility.js](https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/devtools_compatibility.js;l=396?q=devtools_compatibil) file. - 3. Create a new function in [UserMetrics.ts](https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/core/host/UserMetrics.ts;l=351) with an enum parameter that corresponds to the possible values like colorPickerOpenedFrom(type: ColorPickerOpenedFrom): void that calls InspectorFrontendHostInstance.recordEnumeratedHistogram. - 4. Call the new function from Host.userMetrics in the places that you want to log the event. - 5. Create the CL. -2. Update [histograms.xml](https://source.corp.google.com/h/chromium/chromium/src/+/main:tools/metrics/histograms/metadata/dev/histograms.xml) and [enums.xml](https://source.chromium.org/chromium/chromium/src/+/main:tools/metrics/histograms/enums.xml;l=26267?q=tools%2Fmetrics%2Fhistograms%2Fenums.xml) in the Chromium codebase. - 1. Add a new enum in [enums.xml](https://source.chromium.org/chromium/chromium/src/+/main:tools/metrics/histograms/enums.xml;l=26267?q=tools%2Fmetrics%2Fhistograms%2Fenums.xml) with values corresponding to the values in the frontend with name DevTools<HISTOGRAM_NAME> and make sure that enum values 1-1 map to the values you’ve defined in the frontend. - 2. Add the new histogram definition in [histograms.xml](https://source.corp.google.com/h/chromium/chromium/src/+/main:tools/metrics/histograms/metadata/dev/histograms.xml) and set enum name to be the enum you've defined in the 1st step. Make sure that histogram name is the same with the name you've used in the frontend change. - 3. Create the CL. - -## Tracking an action - -1. Implement metric collection in devtools-frontend and create a CL. (Example [CL](https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/3998783)) - 1. Add the action you want to track to the [Action](https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/core/host/UserMetrics.ts;l=379) enum in UserMetrics.ts. - 2. Call Host.userMetrics.actionTaken(Action.YOUR_ACTION) in the places you want to the event. - 3. Create the CL. -2. Update enums in the Chromium side in [tools/metrics/histograms/enums.xml](https://source.chromium.org/chromium/chromium/src/+/main:tools/metrics/histograms/enums.xml;l=26267?q=tools%2Fmetrics%2Fhistograms%2Fenums.xml). - 1. Add the new action to the DevToolsAction enum. - 2. Create the CL. - - -## Metrics Dashboard - -After the both CLs are landed we expect your histogram or action data to be available in [UMA](http://uma/p/chrome/timeline_v2). For seeing them: - -* Select the channel you want to dive into. -* Select the platforms you are interested in (for us, it is Linux, MacOS, Windows, ChromeOS and Lacros) -* Add the metric you want to see: either the histogram name you’ve newly added `DevTools.ColorPickerOpenedFrom` or the generic histogram for action tracking, `DevTools.ActionTaken`. diff --git a/docs/checklist/README.md b/docs/checklist/README.md new file mode 100644 index 000000000000..76d52b5906d8 --- /dev/null +++ b/docs/checklist/README.md @@ -0,0 +1,140 @@ +# Chromium DevTools support checklist (for Blink Intents) + +[goo.gle/devtools-checklist](https://goo.gle/devtools-checklist) + +**Shipping new Web Platform features (WPFs) in Chromium requires tooling support.** + +Many new Web Platform Features (WPFs) can piggyback off of DevTools' general tooling for HTML, DOM, CSS, JavaScript, +WebAssembly, Network, and other aspects — requiring only minimal or no changes to make DevTools behave as expected +in light of the new WPF. This document refers to such cases as _basic tooling_. + +However, some WPFs might warrant larger changes, including brand-new DevTools features. This document refers to such +cases as _extended tooling_. + +It’s the WPF owner’s responsibility to ensure the tooling story is thought through, by answering the question: +_"how would a web developer making use of your new WPF test and debug their code?"_ + +- Basic tooling must be implemented before shipping a new WPF. +- Extended functionality must be considered on a case-by-case basis, and could in some cases be allowed to launch after shipping the WPF. + +This document captures examples of different kinds of WPFs, the tooling support they require, and how this can be achieved. + +*** note +**IMPORTANT:** Please take a look at the [DevTools UI feature checklist](./ui.md) prior +to changing or extending the DevTools user interface (UI). +*** + +[TOC] + +## JavaScript (ECMAScript) language features + +See the [Chromium DevTools support checklist for JavaScript language features](https://goo.gle/v8-checklist). + + +## WebAssembly language features + +See the [Chromium DevTools checklist for WebAssembly features](https://goo.gle/devtools-wasm-checklist). + + +## New HTML elements + +New HTML elements get basic tooling support through the DevTools Elements panel. Verify that inspecting the new element +in the Elements tab looks alright and works as expected (typically, this requires no additional implementation effort). + + +## New WebIDL/DOM interfaces and attributes + +Verify that the new properties show up in the DevTools Console autocomplete functionality (typically, this requires no additional implementation effort). +To enable argument hints for new or changed parameterized functions, run +``` +devtools-frontend/src/scripts/deps/roll_deps.py +``` +to re-generate `devtools-frontend/src/front_end/models/javascript\_metadata/NativeFunctions.js` ([Example CL](http://crrev.com/c/3432787)). + +![](./images/checklist-autocomplete-idl-attribute.png "Console autocompletion for IDL attributes") + + +## New DOM events + +DevTools supports setting breakpoints on DOM events via the Sources tab → Event Listener Breakpoints. Make sure the new event is exposed under the relevant category. + +![](./images/checklist-event-listener-breakpoints.png "Event Listener Breakpoints") + +Pointer: [`front_end/core/sdk/DOMDebuggerModel.ts`](https://source.chromium.org/chromium/chromium/src/+/main:third\_party/devtools-frontend/src/front_end/core/sdk/DOMDebuggerModel.ts;l=766-870;drc=79e812efee4be5e4d4378562f8acebffe9771f20) + + +## CSS + +For CSS WPFs, basic tooling support involves the ability to view and edit styles via the DevTools Styles panel. +This mostly works out of the box, but some minimal changes might be needed depending on the specifics. + +### New CSS at-rules + +WPFs that introduce new CSS at-rules (i.e. `@foo (bar: baz) { … }`) must surface the new at-rules over the Chrome +DevTools Protocol (CDP) so that DevTools can show them in the Styles panel. +Please refer to [goo.gle/devtools-generic-at](https://goo.gle/devtools-generic-at) for instructions and examples on +how to add DevTools support for a new at-rule. + +### New CSS pseudo-classes + +WPFs that introduce a new CSS pseudo-class must surface the new pseudo-class in the Force element state UI within the Styles tab. + +![](./images/checklist-pseudo-classes.png "Pseudo classes in the Styles tab") + +Example for `:target`: [Chromium back-end CL](https://chromium-review.googlesource.com/c/chromium/src/+/2575668), +[DevTools front-end CL](https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/2581544). + +### New CSS properties or values + +To recognize new CSS properties/values in the DevTools Styles panel’s autocomplete functionality, roll +[Chromium’s `css_properties.json5`](https://source.chromium.org/chromium/chromium/src/+/main:third\_party/blink/renderer/core/css/css_properties.json5;drc=be2c473625b9c28a4ff6735547cb0c1b6743f4ae) into the `devtools-frontend` repository by running +``` +devtools-frontend/src/scripts/deps/roll_deps.py +``` +see this [example CL](https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/2972583). + +![](./images/checklist-css-properties.png "CSS property value completion") + + +## Network-related features + +Any WPFs that have the ability to initiate requests or otherwise involve the network stack must ensure such requests +are captured in the DevTools Network tab. + +Some WPFs might warrant extended tooling, for example, [Trust Tokens](http://crbug.com/1126824) got their own tab in +DevTools’ Network panel: + +![](./images/checklist-network-trust-tokens.png "Trust Tokens tab in the Network panel") + + +## PWA features + +WPFs related to Web Application Manifest, service workers, background services, notifications, storage, caching are +covered under the DevTools Application tab. Given the broad scope of features captured here, there is no generic +guidance that applies, other than: review the existing DevTools functionality related to your WPF, and ensure the +new WPF works well with it. + +Depending on the WPF specifics, extended tooling might be warranted. For example, [Trust Tokens](http://crbug.com/1126824) +shipped with a new subpanel under the Application tab: + +![](./images/checklist-application-trust-tokens.png "Trust Tokens tab in the Application panel") + +Reach out to the DevTools team via [devtools-dev@chromium.org](mailto:devtools-dev@chromium.org) prior to sending out +your Intent email. + + +## Warnings, deprecations, removals + +If your Blink Intent is about the deprecation/removal of a WPF, or an otherwise risky change from a Web compatibility +standpoint, the basic tooling support requirement can be satisfied by integrating with DevTools’ Issues panel. See +[how to pipe your messages into the Issues tab](https://docs.google.com/document/d/13zZBu6RG7D23FSWecSy3AHPEdFHJMkp732-uJ5CFbmc) +for details. + +* For issues that should be reported on the browser process, use `devtools_instrumentation::ReportBrowserInitiatedIssue()`. + See its use sites for examples. Browser-side issues may contain information that would be unsafe for a renderer to know. +* For renderer-side issues, use `ExecutionContext::AddInspectorIssue(AuditsIssue)`. Consider adding a static method to + `AuditsIssue` which is defined in `third_party/blink/renderer/core/inspector/inspector_audits_issue.h` that creates and + reports the issue. `inspector_audits_issue.h` is crafted such that it minimizes dependencies (and hence can be included + without adding too much overhead). ([Example CL](https://chromium-review.googlesource.com/c/chromium/src/+/2892206)) + +Try to avoid adding a new Console message — these are deprecated in favor of the Issues panel. diff --git a/docs/checklist/images/checklist-application-trust-tokens.png b/docs/checklist/images/checklist-application-trust-tokens.png new file mode 100644 index 000000000000..1f28b68b32c9 Binary files /dev/null and b/docs/checklist/images/checklist-application-trust-tokens.png differ diff --git a/docs/checklist/images/checklist-autocomplete-idl-attribute.png b/docs/checklist/images/checklist-autocomplete-idl-attribute.png new file mode 100644 index 000000000000..721c6db4f2df Binary files /dev/null and b/docs/checklist/images/checklist-autocomplete-idl-attribute.png differ diff --git a/docs/checklist/images/checklist-css-properties.png b/docs/checklist/images/checklist-css-properties.png new file mode 100644 index 000000000000..d95ac08505c9 Binary files /dev/null and b/docs/checklist/images/checklist-css-properties.png differ diff --git a/docs/checklist/images/checklist-event-listener-breakpoints.png b/docs/checklist/images/checklist-event-listener-breakpoints.png new file mode 100644 index 000000000000..00a11f9e9435 Binary files /dev/null and b/docs/checklist/images/checklist-event-listener-breakpoints.png differ diff --git a/docs/checklist/images/checklist-network-trust-tokens.png b/docs/checklist/images/checklist-network-trust-tokens.png new file mode 100644 index 000000000000..b7ab570b21ff Binary files /dev/null and b/docs/checklist/images/checklist-network-trust-tokens.png differ diff --git a/docs/checklist/images/checklist-pseudo-classes.png b/docs/checklist/images/checklist-pseudo-classes.png new file mode 100644 index 000000000000..eb9914b0a06b Binary files /dev/null and b/docs/checklist/images/checklist-pseudo-classes.png differ diff --git a/docs/checklist/javascript.md b/docs/checklist/javascript.md new file mode 100644 index 000000000000..813b9da1215a --- /dev/null +++ b/docs/checklist/javascript.md @@ -0,0 +1,376 @@ +# Chromium DevTools support checklist for JavaScript language features + +[goo.gle/v8-checklist](https://goo.gle/v8-checklist) + +Implementation for new language features (NLF) are often intrusive and affect many parts of +[V8](https://v8.dev). This sometimes causes the debugger to not work seamlessly with the NLF +out of the box. We generally make the distinction between _Basic functionality_ and _Extended +functionality_ when talking about debugger support: + +- Basic functionality is required for every NLF in order to launch. The debugger must not crash + or act in a confusing way when interacting with the NLF. For example, stepping into a `Proxy` + trap handler should be possible. +- Extended functionality is often just nice-to-have, but in some cases required for launch. + This includes debugging capabilities specific to the language feature. For example, catch + prediction should work as expected for `Promise`s. + +This document attempts to list all relevant aspects of V8’s JavaScript debugger that constitute +basic functionality (checkout [this document](https://goo.gle/devtools-wasm-checklist) for V8's +WebAssembly debugger features). Items on the list may not apply to every language feature, +depending on its nature. + +*** note +**IMPORTANT:** Please take a look at the [DevTools UI feature checklist](./ui.md) prior +to changing or extending the DevTools user interface (UI). +*** + +[TOC] + +## Console printing + +DevTools offers a REPL through the Console panel. Logging a value should print reasonable output. + +### Affected + +All NLFs that affect how values should be printed in a REPL, such as NLFs that introduce new primitives, new `RegExp` flags, etc. + +### How to test + +Open DevTools, select the Console panel, and enter a source snippet with the NLF. The printed result should look alright. + +### Reading material + +[Example CL that adds printing support for a new `RegExp` flag](https://chromium-review.googlesource.com/c/v8/v8/+/2848460) + + +## Syntax highlighting and pretty-printing + +DevTools provides syntax highlighting and pretty-printing for JavaScript sources. + +### Affected + +All NLFs that introduce new syntax. + +### How to test + +Open DevTools, select the Sources panel, and create a new source snippet with the NLF. The syntax highlighting of the source +should look alright. This is handled by [CodeMirror](https://codemirror.net/) inside of Chromium DevTools. + +Clicking on the pretty-printing button on the bottom left ("{}") should yield reasonable results. The formatting relies on the +[acorn](https://github.com/acornjs/acorn) parser, which needs to support the NLF in question for this to work. + + +## Stack traces + +Stack traces is the most often used way for developers to debug issues. Aside from the default `Error.stack` string, we also +offer a way for user code to override how to format the `stack` property, and collect a more detailed structured stack trace +for DevTools. + +Sometimes, due to the way a feature is implemented, there may be stack frames that show up on the stack trace when they should +not, or vice versa. + +For runtime exceptions, we look for the closest code position that has a source position attached. That source position is used +as expression position for the exception. For syntax errors, we should report the correct location of the syntax error via +[`MessageHandler::ReportMessage()`](https://source.chromium.org/chromium/chromium/src/+/main:v8/src/execution/messages.h;l=174-176;drc=4e40b002b46c019d18eae68b5e5a342605609d95). + +Note that `Error.stack` is only collected for `Error` objects, at the time the `Error` object is constructed. This may be different +than the stack trace passed to DevTools via [`JSMessageObject`](https://source.chromium.org/chromium/chromium/src/+/main:v8/src/objects/js-objects.h;l=1264-1345;drc=82dff63dbf9db05e9274e11d9128af7b9f51ceaa). + +### Affected + +NLFs that can cause an exception to be thrown, or can call into another function that throws. + +### How to test + +When throwing inside the NLF, or with it on the stack, the stack trace including source positions should make sense. Also check +the structured stack trace when the exception is not caught and logged into Chrome's DevTools console. + +Repeat with the "Disable async stack traces" checkbox in the Preferences checked. + +### Test cases + +Test cases for stack traces is mandatory, if there is any way the NLF can interact with throwing exceptions. For examples look +for `mjsunit` tests with `stack-trace` in their names. + +### Reading material + +[Design doc for debugging support for tail-calls](https://docs.google.com/a/google.com/document/d/1Bk4QahtaT-XzrMlHTkm0SVol3LoKXTrC9E7INxJBHrE/edit?usp=drive\_web) + +## Async stack traces + +DevTools offers a way to show async stack traces by stitching together stack traces collected at the +location where the callback is passed, and the actual location of the exception inside the callback. + +The canonical example of this is throwing inside a `setTimeout` callback. The async stack trace will +consist of the stack trace of the error plus a stack trace captured at the `setTimeout` call-site. + +The instrumentation is based on four [`ayncTask*` methods](https://source.chromium.org/chromium/chromium/src/+/main:v8/include/v8-inspector.h;l=370-375;drc=aafd25ffbc72935b52fee731f957e5827c73a096). Namely `asyncTaskScheduled`, `asyncTaskStarted`, `asyncTaskFinished` and `asyncTaskCancelled`. +V8 has a [higher-level interface](https://source.chromium.org/chromium/chromium/src/+/main:v8/src/debug/debug-interface.h;l=351-352;drc=e6fc2038d73ef96ff47deda3146d94d25530e13b) that translates Promise events (such as `await`, `.then`, etc) to these for `asyncTask*` methods. + +### Affected + +NLFs touching promises or callback scheduling. + +### How to test + +Throw or pause inside a new language feature and check either the call stack sidebar panel in "Sources" +or use a `console.trace` and check the async stack trace in the console. + +### Test cases + +Test cases for async stack traces are mandatory, if there is any way the NLF interacts with callback scheduling or +Promises. For examples look in V8 `inspector` tests with `async-stack` in their name (e.g. [here](https://source.chromium.org/chromium/chromium/src/+/main:v8/test/inspector/debugger/async-stack-await.js)). + +## Catch prediction + +Aside from offering stack traces, V8's debugger supports DevTools' pause-on-exception feature. This comes in two flavors: +pause on all exceptions, and pause on uncaught exceptions. In both cases, we break at the throw site (not at the `catch`, +or any rethrow via `try`-`finally`). + +For the former, this is as easy as breaking in the debugger on `Isolate::Throw()`. For the latter, we have to predict whether +the thrown exception will be caught or otherwise handled (for example by a `Promise`'s catch handler). + +### Affected + +NLFs that can cause an exception to be thrown, or can call into another function that throws. + +### How to test + +When pause-on-exception is enabled, and throwing inside the NLF or with it on the stack, the script should pause as expected. + +Repeat with the "pause on caught exception" checkbox checked. + +### Test cases + +Test cases for exception prediction is mandatory, if there is any way the NLF can interact with exceptions, be it by throwing +exceptions, or by relying on `try`-`catch` or `try`-`finally` in its implementation. Look for `mjsunit` tests that contain the +string `setBreakOnException` or `setBreakOnUncaughtException`. + +### Reading material + +[Design doc for exception prediction for async-await](https://docs.google.com/a/google.com/document/d/1ef1drN6RTRN7iDB8FXJg\_JJZFNObCFbM1UjZWK\_ORUE/edit?usp=drive\_web) + + +## Breakpoints + +One of the most important features is setting break points. The semantics should be obvious. + +Break locations are function calls, return sites, and statements. Special care are necessary for loops: for example, in `for`-loops +we do want to be able to break separately at the loop entry, condition evaluation, and increment. + +When setting a break point at an arbitrary source position, we actually check for the closest breakable source position, and move +the break point there. Consecutive debug break events at the same source position are ignored by the debugger. + +### Affected + +NLFs that change generated code, and especially once that introduce new break locations. + +### How to test + +Open DevTools and set break points in parts of script related to the NLF, then run the script. + +### Test cases + +Look for `mjsunit` tests with `debug-break` in their names. + + +## Stepping + +Stepping is the logical consequence to breakpoints, and is based on the same mechanism in the debugger. We differentiate between + +* Step out, which takes us to the next break location in the caller. +* Step next, which takes us to the next break location while ignoring calls into other functions. Note that this includes recursive + calls. Step next at a return site is equivalent to a step out. +* Step in, which takes us to the next break location including calls into another function. +* Step frame, which takes us to another function, either a callee or a caller. This is used for framework blackboxing, where the V8 + inspector is not interested in stepping in the current function, and wants to be notified once we arrive at another function + +### Affected + +NLFs that are affect breakpoints + +### How to test + +Break inside the part of script related to the NLF, and try stepping in, next, and out. + +### Test cases + +Look for `mjsunit` tests with `debug-step` in their names. + +### Reading material + +[Design doc on stepping in async-await](https://docs.google.com/a/google.com/document/d/1nj3nMlQVEFlq57dA-K8wFxdOB5ovvNuwNbWxBhcBOKE/edit?usp=drive\_web) + + +## Frame inspector + +The frame inspector in V8 offers a way to a way to introspect frames on the call stack at the debug break. For the top-most frame, +the break location is that of the debug break. For frames below the break location is the call site leading to the frame above. + +For each frame, we can + +- inspect the scope chain at the break location with the scope iterator, +- find out whether it's called as constructor, +- find out whether we are at a return position, +- get the function being called, +- get the receiver, +- get the arguments, and +- get the number of stack-allocated locals. + +For optimized code, we use the deoptimizer to get hold of receiver, arguments and stack locals, but this is often not possible, and we +get the `optimzed_out` sentinel value. + +### Affected + +NLFs that affect the way V8 calls functions. + +### How to test + +When paused inside the function affected by the NLF, the Call Stack view in the DevTools' Source panel should show useful information. + +### Test cases + +Take a look at `test/mjsunit/wasm/frame-inspection.js`. + + +## Scope iterator + +The scope iterator in V8 offers a way to introspect the scope chain at the break location. It includes not only the scopes outside of +the current function, but also scopes inside it, for example inner block scopes, catch scopes, with scopes, etc. + +For each scope inside the current function, we can materialize an object representing local variables belonging to it. For scopes +outside the current function this is not possible. + +We can use the scope iterator to alter the value of local variables, unless we are inside an optimized frame. + +### Affected + +NLFs that introduce new scopes. + +### How to test + +When paused in DevTools inside the scope introduced by the NLF, the "Scope" view on the Sources panel should show useful information. +Scopes that are introduced by the NLF for desugaring purposes may better be hidden. + +### Test cases + +Take a look at `test/mjsunit/debug-scopes.js`. + +### Reading material + +[CL that introduces hidden scopes](https://chromium.googlesource.com/v8/v8/+/672983830f36222d90748ff588831b6dae565c38) + + +## Debug evaluate + +With debug-evaluate, V8 offers a way to evaluate scripts at a break, attempting to behave as if the script code was executed +right at the break location. It is based on the frame inspector and the scope iterator. + +It works by creating a context chain that not only references contexts on the current context chain, but also contains the +materialized stack, including arguments object and the receiver. The script is then compiled and executed inside this context chain. + +There are some limitations, and special attention has to be paid to variable name shadowing. + +Side-effect-free debug-evaluate statically determines whether a function should throw. You should check whether to update the +whitelist in `src/debug/debug-evaluate.cc`. + +### Affected + +NLFs that are also affected by the scope iterator and frame inspector. + +### How to test + +Use the DevTools console to run scripts at a debug break. In particular the preview shown in the DevTools console by default indicates +whether the side-effect detection works correctly (i.e. whether you updated the whitelist correctly). + +### Test cases + +Look for mjsunit tests with "debug-evaluate" in their names. + +### Reading material + +This [tea-and-crumpets](https://drive.google.com/file/d/0BwPS\_JpKyELWTXV4NGZzS085NVE/view) [presentation](https://docs.google.com/a/google.com/presentation/d/18-c04ri-Whcp1dbteVTqLtK2wqlUzFgfU4kp8KgyF3I/edit?usp=drive\_web) + +Debug-evaluate without side effect [doc](https://docs.google.com/document/d/1l\_JzDbOZ6Cn1k0c5vnyEXHe7B2Xxm7lROs1vYR3nR2I/edit) and [presentation](https://docs.google.com/presentation/d/1u9lDBPMRo-mSQ6mmO03ZmpIiQ-haKyd9O4aFF0nomWs/edit) + + +## Code Coverage + +Code coverage gathers execution counts and exposes them to developers through the Inspector protocol. + +### Affected + +NLFs that contain control flow (e.g branches, loops, etc.). + +### How to test + +Run `d8` with `--lcov` and check whether the produced coverage information is correct. E.g. like this: + +``` +./d8 --lcov=cov.info test.js +genhtml cov.info -o coverage +``` + +Then navigate your browser to `coverage/index.html`. + +### Test cases + +`test/mjsunit/code-coverage-block.js` + +### Reading material + +Design doc: [go/v8-designdoc-block-code-coverage](http://go/v8-designdoc-block-code-coverage) + + +## Heap profiler + +The heap profiler is a tool usually used to find out what is taking so much memory, and find potential memory leaks. It is an object graph visitor. + +### Affected + +NLFs that change object layouts or introduce new object types + +### How to test + +Take a heap Snapshot in DevTools' Profiler panel and inspect the result. Objects related to the NLF should fan out to all objects it references to. + +### Test cases + +Take a look at `test/cctest/test-heap-profiler.cc`. + +## Restart frame + +DevTools allows restarting of some stack frames, not just the top-level one. The feature is implemented by throwing a termination exception and unwinding the stack +until after the function we want to restart, and then re-invoking the function. This only works for certain functions, e.g. async functions can't be restarted +as that would require rolling back the underlying generator. + +### Affected + +NLFs that change function execution or require a function to carry state (e.g. async functions +need a generator that can't be reset). + +### How to test + +While paused, right click a stack frame with the NLF in the call stack view and select "Restart frame". If the NLF prevents the frame from being restarted, then +the "Restart frame" menu item must be disabled, otherwise the frame must be properly restarted. + +### Test cases + +Take a look in `test/inspector/debugger/restart-frame/*`. + +## LiveEdit + +LiveEdit is a feature that allows for script content to be replaced during its execution. While it has many limitations, the most often use case +of editing the function we are paused in and restarting said function afterwards. + +### Affected + +NLFs that affect code execution + +### How to test + +Open DevTools and break inside the part of script affected by the NLF. Change the code inside the function with the NLF and save the script. + +### Test cases + +Look for `mjsunit` tests with `liveedit` in their names. diff --git a/docs/checklist/navbar.md b/docs/checklist/navbar.md new file mode 100644 index 000000000000..871c70a2ea8d --- /dev/null +++ b/docs/checklist/navbar.md @@ -0,0 +1,10 @@ +# Chromium DevTools support checklist + +[logo]: https://github.com/ChromeDevTools/devtools-logo/raw/master/logos/png/devtools-circle-48.png +[home]: /docs/checklist/README.md + +* [Home][home] +* [Checklist for JavaScript features](./javascript.md) +* [Checklist for WebAssembly features](./webassembly.md) +* [Checklist for UI features](./ui.md) +* [Chromium DevTools Documentation](/docs/README.md) diff --git a/docs/checklist/ui.md b/docs/checklist/ui.md new file mode 100644 index 000000000000..300963bf58d0 --- /dev/null +++ b/docs/checklist/ui.md @@ -0,0 +1,113 @@ +# Chromium DevTools UI feature checklist + +[goo.gle/devtools-ui-checklist](https://goo.gle/devtools-ui-checklist) + +Chrome DevTools is used by most web developers nowadays. In user interviews and +informal conversations web developers voice the opinion that Chrome DevTools is +great, but they have a hard time finding the right tool for the job. Naturally, +the Chrome DevTools suite will grow over time, as the Web Platform keeps on +growing. Without intervention, this will *clutter* the UI of Chrome DevTools +even more. This document here should serve as a checklist when new features are +added to Chrome DevTools' UI. + +Please reach out to [hablich@chromium.org](mailto:hablich@chromium.org) (PM) or +[petermueller@chromium.org](mailto:petermueller@chromium.org) (UXD) with any +questions and concerns. + +[TOC] + +In general there are some categories which are important to look at: + +## Measurability + +We should be able to define and measure the success of a feature. Ideally, we +treat every feature as an experiment which needs to prove itself before it can +stay forever. (not literally with an experiment checkbox, but as a mental model) + +* Can we clearly state what our **goal** is that we want to solve? +* Can we formulate a **hypothesis/assumption**, how we believe our feature + will solve this goal? +* Can we **validate** this and see if our feature actually does what it + should? +* And finally, can we **remove/revert** a feature, if we see that it's not + used at all? + +## Strategic fit + +Does a new feature directly support our strategy? Is a feature weighted against +our backlog? Does a feature help us in reaching our strategic goal? If not, we +should de-prioritize it. + +## Relevance + +How relevant is a feature to our user base as a whole? + +Does a feature support one of our core developer journeys or is it related to a +niche area? + +* Are we over-fitting to a tiny niche part of our user base? +* From the perspective of the implementing team, each feature is super + relevant, needs to be discoverable and should sit in the prime UI. +* We as a product team should carefully choose which user journeys are our product + core and if a new feature adds distractions to these journeys or enhances them. +* Is a feature relevant for the mainstream of non-Google engineers? Or is it + mostly a Google-internal feature? +* Is it adequate to expose a feature to all of DevTools' users, even if only a + tiny fraction will ever use it? +* Should the feature be shipped to all of DevTools' users or rather be made + available as a DevTools extension? + +## Potential impact + +Is a feature a life-saver or just a quality-of-life improvement? + +* We should prioritize impact for our users. +* Can developers live without this feature? How do they solve the problem + right now? What's the worst that would happen if we don't develop this + feature? + +## UI complexity + +Is a feature easy to revert/remove if we figure out that it's not used? Or will +it stay forever in the UI and clutter it even more? + +What's the least amount of work/UI we need to test how a new feature is actually +used? + +Is this extending an existing feature or creating something new? Which (and how +many) other features are in its vicinity on the screen and panel? + +* We should favor solutions, which can be easily reverted or removed if we + figure out that a feature is not really used. Deeply integrated UI solutions + tend to stay forever. +* Instead of going *all-in* as the default, we should add features + incrementally and measure along the way if a feature is quickly becoming + mainstream or stays rather niche. Based on this the next iteration can + either extend the feature or further deemphazise it in the UI. +* UIs should not be overloaded. +* Avoid requiring major UI reworks if it is just extending an already existing + feature +* We shouldn't default to adding a new "panel" for every feature, just because + the feature team is looking at the feature in isolation. + +## Placement and discoverability + +How many user interactions are needed until the user is using the feature +(without Command+P)? + +* Sensible thresholds: + * **< 3 interactions**: Very accessible, good if it is intended to be used + by most users + * **3 < 6 interactions**: Likely somewhere in a front panel, likely good + for most of the features + * **6 < interactions**: This is hard to find! + +The more often something is used, the easier it should be able to be opened. + +## Target audience + +Which user type is going to be using this feature? How many of these users? + +Will this primarily be used while debugging production instances of web +applications (obfuscated code, no source mapping) or dev versions (local, source +mapping, source code available)? diff --git a/docs/checklist/webassembly.md b/docs/checklist/webassembly.md new file mode 100644 index 000000000000..3c105424c695 --- /dev/null +++ b/docs/checklist/webassembly.md @@ -0,0 +1,92 @@ +# Chromium DevTools checklist for WebAssembly features + +[https://goo.gle/devtools-wasm-checklist](https://goo.gle/devtools-wasm-checklist) + +Implementation of new WebAssembly features should take into account the developer experience in Chromium from the +get-go to ensure a great first impression when it is shipped to developers. This document attempts to list all the +relevant aspects of the developer tools that constitute basic functionality, which should be available when the new +features launch (see [shipping criteria for WebAssembly +features](https://v8.dev/docs/wasm-shipping-checklist#when-is-a-webassembly-feature-ready-to-be-shipped)). + +It intentionally doesn't cover extended functionality, which is optional but often desirable, and in some cases +also required for a launch. This includes debugging capabilities specific to the feature in question. + +This document is the WebAssembly counterpart to the [Chromium DevTools support checklist for JavaScript language +features](https://goo.gle/v8-checklist), which is specifically about JavaScript language features, + +*** note +**IMPORTANT:** Please take a look at the [DevTools UI feature checklist](./ui.md) prior +to changing or extending the DevTools user interface (UI). +*** + +[TOC] + +## Breakpoints and stepping + +Chromium DevTools handles breakpoints and stepping via the Liftoff tier in V8. + +### Affected + +All features that introduce new instructions or change the semantics of existing instructions. These will need to be +explicitly supported in the Liftoff compiler. + +### How to test + +[User journeys for breakpoints and stepping](https://docs.google.com/document/d/1XBlUbyYfPsn1OuCpq2F-O7E3zvsfa94ZFsiIcnq2w7I#bookmark=id.gxratadmkb83) + +Create a `.wasm` file with a function inside that uses the new feature and serve it from a (local) test page, open Chromium DevTools, +select the Sources panel and locate your `.wasm` file in the Page tree. Now try to set a breakpoint in the function with the new +instruction(s), make sure this breakpoint is hit when the function is run the next time, and also very important, check that this also +works upon reload when the relevant code runs during startup. Likewise try to step into the function, through it and out of the function. + + +## Scope view + +The Scope view is part of the Sources panel of the Chromium DevTools, which shows when paused on a breakpoint or during stepping. + +### Affected + +All features that affect instructions or introduce new instructions or types. + +### How to test + +[User journeys for the scope view](https://docs.google.com/document/d/1XBlUbyYfPsn1OuCpq2F-O7E3zvsfa94ZFsiIcnq2w7I#bookmark=id.9ki5pf2b90dj) + +Create a `.wasm` file with a function inside that uses the new feature and serve it from a (local) test page, open Chromium DevTools, +select the Sources panel and locate your `.wasm` file in the Page tree. Set a breakpoint inside the function with the new / changed +instruction(s) and hit the breakpoint by invoking the function. Now when paused on the function make sure that the Scope view shows +reasonable / correct information. + + +## Syntax highlighting + +Chromium DevTools provides syntax highlighting for WebAssembly disassembly. + +### Affected + +All features that affect the disassembly in any way, specifically features that introduce new instructions, new types, or change the +disassembly of existing instructions. + +### How to test + +[User journeys for syntax highlighting](https://docs.google.com/document/d/1XBlUbyYfPsn1OuCpq2F-O7E3zvsfa94ZFsiIcnq2w7I#bookmark=id.sfk1pjqn7d2d) + +Create a `.wasm` file that uses the new feature and serve it from a (local) test page, open Chromium DevTools, select the Source panel and +locate your `.wasm` file in the Page tree. The syntax highlighting of the disassembly should look alright. The syntax highlighting is handled +by [CodeMirror](https://codemirror.net/), inside of Chromium DevTools. + + +## Performance profiling + +Chromium DevTools allows developers to take performance traces of their applications via the Performance panel. + +### Affected + +All features that introduce new instructions or affect the way that WebAssembly functions are executed. + +### How to test + +[User journeys for performance profiling](https://docs.google.com/document/d/1XBlUbyYfPsn1OuCpq2F-O7E3zvsfa94ZFsiIcnq2w7I/#bookmark=id.huv4j7664qhx) + +Create a `.wasm` file with a function inside that uses the new feature and serve it from a (local) test page, open Chromium DevTools, select +the Performance panel. Now run the function a with some significant payload for a reasonable amount of time and take a performance profile. diff --git a/docs/committers_policy.md b/docs/committers_policy.md index d3d457f5e72c..9c7f685f5254 100644 --- a/docs/committers_policy.md +++ b/docs/committers_policy.md @@ -16,7 +16,7 @@ In a nutshell, contribute 20 non-trivial patches and get at least three differen * understanding of the projects' code base and coding style, and * ability to write good code (last but certainly not least) -A current committer nominates you by sending email to [chrome-devtools-committers@googlegroups.com](mailto:chrome-devtools-committers@googlegroups.com) containing: +A current committer nominates you by sending email to [chrome-devtools-committers@chromium.org](mailto:chrome-devtools-committers@chromium.org) containing: * your first and last name * your email address in Gerrit @@ -25,7 +25,7 @@ A current committer nominates you by sending email to [chrome-devtools-committer Two other committers need to second your nomination. If no one objects in 5 working days (U.S.), you're a committer. If anyone objects or wants more information, the committers discuss and usually come to a consensus (within 5 working days). If issues cannot be resolved, there's a vote among current committers. -Once you get approval from the existing committers, you'll be added to [chrome-devtools-committers@googlegroups.com](mailto:chrome-devtools-committers@googlegroups.com) and to the project's committers group granting you additional review permissions. +Once you get approval from the existing committers, you'll be added to [chrome-devtools-committers@chromium.org](mailto:chrome-devtools-committers@chromium.org) and to the project's committers group granting you additional review permissions. 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." diff --git a/docs/contributing/README.md b/docs/contributing/README.md new file mode 100644 index 000000000000..7e2e0f19d6b9 --- /dev/null +++ b/docs/contributing/README.md @@ -0,0 +1,333 @@ +# Chromium DevTools Contribution Guide + +[goo.gle/devtools-contribution-guide](https://goo.gle/devtools-contribution-guide) + +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) + + +## Quick Start + +*** aside +**TL;DR**: Chrome DevTools is a web application! + +It's TypeScript and CSS. It's open +source. And it's hackable. That's what this doc is about. +*** + +This section provides a condensed tutorial for contributing to the Chromium +developer tools front-end (for the impatient). + +### Hello World + +* Open DevTools to the Elements panel. +* Undock it via the 3-dots menu in the top-left. +* Make sure Elements panel is visible. +* Use the keyboard shortcut to Open DevTools (_Ctrl+Shift+I_ or _Cmd-Option-I_), + actually DevTools-on-DevTools. + +![](./images/quickstart-inception.png "DevTools Inception") + +You're now inspecting the inspector! See more at the [The Hello World of Chrome +DevTools Hacking](https://medium.com/@paul_irish/1e671bf659bb) by +[paulirish@chromium.org](mailto:paulirish@chromium.org). + +### How to Hack on DevTools + +Read the [Get the Code](../get_the_code.md) documentation for how to setup a +working checkout and build of Chromium DevTools, and consult the [Testing +Guide](../../test/README.md) for information how to test your changes. + +#### Hack on DevTools front-end + +Make any changes you like in the front-end. + +**Refreshing** is a little tricky when hacking on devtools. If your focus is +within the DevTools, then _Ctrl-R_ will reload the page it's inspecting. So, +that'd be fine if you _Ctrl-R_ in your DevTools-on-DevTools window. + +*** note +**Tip**: _Alt-R_ or _Option+R_ will reload the DevTools instance you're focused +on. +*** + +**Caching**: As this is a fresh DevTools profile, the "Disable cache" checkbox +is off. You'll want to turn that on, pronto. + +#### Inspector.html query parameters + +There are a few query parameters worth explaining: `http://localhost:8090/front_end/inspector.html?can_dock=true&dockSide=right&ws=localhost:9222/devtools/page/1FFDE891-34F1-485C-A0CB-066EBF852E53` + +* The `can_dock=true&dockSide=right` can help you emulate dock-to-right +* The `ws=…` query parameter defines the websocket connection. + +#### Hacking FAQ + +1. *Why aren’t changes shown in the Sources panel when I edit the DevTools source?* + + The DevTools source files might be cached. Try checking the setting “Disable + cache (while DevTools is open)” in DevTools' Preferences. + +2. *What about refreshing and making changes quickly?* + + For productive development, you should use `--custom-devtools-frontend` as + listed in the [Get the code](../get_the_code.md) documentation. + +3. *Can I make a pull request?* + + Well, we don't have pull requests, but we can do something similar. + Read about it in the [Contribution Process](#Contribution-process) + +4. *How do I change branches in git, pull changes from main, etc?* + + The [`depot_tools` tutorial](http://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot\_tools/docs/html/depot_tools_tutorial.html#_creating_uploading_a_cl) is infinitely useful here. + +5. *I have more questions, and I can't find a good answer…* + + Ping the chrome devtools mailing list: [groups.google.com…google-chrome-developer-tools](https://groups.google.com/forum/?fromgroups#!forum/google-chrome-developer-tools) + +6. *I can't see my local changes in DevTools. Why?* + + * You need to reload DevTools via _Alt+R_ or _Option+R_. + * If "Opening in existing browser session" is printed after you run the command to launch Chrome with the `--custom-devtools-frontend` argument, close the browser session in question and re-run the command. + * (Make sure you've rebuilt the codebase after applying your changes) + +### Understanding the Codebase + +Make full use of chromium codesearch. [cs.chromium.org](http://cs.chromium.org) is invaluable. + +* Add `f:front_end` to a search to scope it to the devtools frontend +* Add `-f:out` to exclude the minified devtools JS. Add `-f:test` to ignore various test files. + +#### How DevTools Works + +DevTools is a web app that talks the [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) over a WebSocket (or an internal IPC bridge) to a [backend](https://cs.chromium.org/chromium/src/third_party/blink/renderer/core/inspector/) within Blink's C++. The [devtools-frontend/docs folder](https://github.com/ChromeDevTools/devtools-frontend/tree/main/docs) is the best current documentation on the various components of DevTools, including architecture, testing, etc + +**Protocol & Backend connection**: +Read the fantastic [Contributing to Chrome DevTools Protocol](https://docs.google.com/document/d/1c-COD2kaK\_\_5iMM5SEx-PzNA7HFmgttcYfOHHX0HaOM/edit) guide, and check out the [Chrome DevTools Protocol page](https://chromedevtools.github.io/devtools-protocol/) especially *Monitoring the protocol* section. + +#### How Chromium works + +* [Chrome University 2018 - YouTube](https://www.youtube.com/playlist?list=PL9ioqAuyl6UIFAdsM5KU6P-hRJdh-BPmm) +* [How Blink Works](https://bit.ly/how-blink-works) + +#### Compiling Chrome + +Of course, you'll need the [full checkout of Chromium](https://www.chromium.org/developers/how-tos/get-the-code). + +### Contribution process + +This section provides a TL;DR of the contribution process, please check out the +[Contributing changes to Chromium DevTools](./changes.md) page for a more detailed +description. + +#### Writing your patch + +The patch process helps keep the project running smoothly. This way all efforts +are coordinated and as little effort as possible is spent in patches that won't +be accepted. + +* We need a ticket filed on [crbug.com](http://crbug.com) to keep track of the work. + Find an existing or file a new one. +* If you can, comment on the ticket that you'd like to work on, in case the team has + a good reason why it hasn't been done yet. +* Do your development. +* Don’t worry about creating lots of small commits or writing lengthy commit messages, + nobody will see your individual commits. All of your commits for a single patch will + land as a single squashed commit in the repo. When you’re uploading your patch, + you’ll have a chance to write the patch description (similar to a Pull Request + description). +* If you create a new file, add a license notice at the top of it: + +``` +// Copyright 2024 The Chromium Authors. All rights reserved. +// Use of this source code is governed by a BSD-style license that can be +// found in the LICENSE file. +``` + +#### Preparing your patch + +If your patch is finished, we have a few helpful tools to make sure your patch looks good. + +As part of the presubmit check, we will automatically run these. You can also run specific +presubmit checks by using our `npm` commands: + +* `npm run lint` to perform [ESLint](http://eslint.org) and [Stylelint](http://stylelint.io) + checks. + +To run these presubmit checks without uploading, you can run `git cl presubmit --upload`. + +Read the [DevTools TypeScript Style Guide](http://goo.gle/devtools-tsstyle) for +details about the TypeScript code style. + +If you are an external contributor, and it’s your first patch, you’ll need to create an +account on [chromium-review.googlesource.com](https://chromium-review.googlesource.com/dashboard/self) and make sure to add yourself to the AUTHORS file, see the section about +[Legal stuff](#Legal-stuff) for details. + +#### Submitting Your Patch For Review + +Once you’re done preparing your patch, it’s time to upload your changes. + +*** note +**Tip:** If you need extra guidance here, try these resources: + +* [Install depot tools](https://www.chromium.org/developers/how-tos/install-depot-tools) + * [depot_tools_tutorial](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot\_tools/docs/html/depot_tools_tutorial.html#_creating_uploading_a_cl) + * [meowni.ca/chromium-101/#send-your-code-for-review](http://meowni.ca/posts/chromium-101/#send-your-code-for-review) + * [developer.chrome.com/devtools/contributing-legacy#step-6-upload-your-patch](https://developer.chrome.com/devtools/docs/contributing-legacy#step-6-upload-your-patch) +*** + +After that, you are ready to start the patch upload: + +``` +# upload your patch to codereview… +git cl upload +``` + +*** note +**Gotcha**: If you see `git: 'cl' is not a git command`, then you need to +[add `depot_tools`](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up) repo to your `PATH`. +*** + +Your editor prompts you to write the patch description. + +**Tips on writing a good patch description:** + +* CL for DevTools can go to two different repositories: + * If you are working on backend changes on chromium prefix your changelist (CL) title with `[DevTools]` + * e.g.: `[DevTools] Fix DOM breakpoints sidebar pane exception` + * For changelists (CLs) in devtools-frontend do **not** add the `[DevTools]` prefix + * e.g. `Fix DOM breakpoints sidebar pane exception` +* Explain the change in as much detail as you like. +* When your patch is committed, the first line of the CL is used as the git commit title and the + rest is used as the full git description. +* Try to keep your CL title and description to 80 characters per line. +* Add a `Bug: ` or `Fixed: ` referencing the ID of the [crbug](http://crbug.com) + that your patch is meant for. + +Save and exit the editor to finalize the patch submission. + +Afterwards, you'll get the code review URL e.g. +``` +remote: New Changes: +remote: https://chromium-review.googlesource.com/#/c/chromium/src/+/90292 Fixes [WIP] +``` + +At this point, your patch is on the code review server, but it hasn't been sent to any +reviewers yet. You can upload WIP (work-in-progress) patches here as you develop. +Just like putting a branch on your github repo, but not submitting a PR yet. + +**Adding Reviewers For Your Patch:** + +Once you're ready to add a reviewer, visit that URL, confirm your patch looks how you +expect, and hit “START REVIEW“ on the top. + +Don't know who should review your change? Click the “SUGGEST REVIEWERS“ button on the top +right. You need a review from the owners of the file. + +In the message field, you can add PTAL (Please Take A Look) or whatever other message +you want. + +*** note +**Tip**: You can find all commonly used abbreviations [here](https://www.chromium.org/glossary). +*** + +Now, if you're ready for it to be reviewed, click the “SEND AND START REVIEW“ button: +![](./images/quickstart-gerrit-reviewers.png "Adding reviewers for your patch in Gerrit") + +You will be notified by email about any new messages from the reviewers. + +#### Updating Your Patch in the Review Process + +If reviewers will ask you to change something in your code, follow these steps: + +1. Make sure you are on your branch. +2. Run `gsync client`. +3. Optionally, pull latest changes and rebase them with: `git pull --rebase origin main`. +4. Commit locally to your branch. +5. Run the linters on your code (e.g. style, coding conventions) via `npm run lint`. +6. Finally, upload everything to the server again with `git cl upload`. +7. Once complete, add a comment similar to "comments addressed, please take a look". + Without a comment, reviewers will not know about your new patchset. + +*** note +**Tip**: Make sure you click “REPLY“ every time you’ve added a new set of inline +comments, otherwise they are in draft mode and only you can see them. +*** + +Once the review is given a “LGTM (Looks Good To Me) by a reviewer, you can add it +to the commit queue (CQ). To add to the commit queue, click the “SUBMIT TO CQ“ +button. This will start a final run of tests and land it after a green run. + +**\\o/** + +#### Patch FAQ + +* *What do I do if my CL fails unrelated tests in the commit queue?* + + If the test failures look unrelated to DevTools (i.e. Blink tests), + then try re-submitting it to the commit queue. + +* *`git cl` is saying there's no owner selected.* + + Ignore it, you'll be selecting a reviewer in the web UI. + +* *Tests?* + + You may be asked by a reviewer to write a test. If so, read + the [Testing Guide](../../test/README.md). + +* *How do I update an existing CL with a new version of the patch?* + + When pushing an update, the system automatically remembers which remote issue + is attached to your local branch. So nice. + +* *How do I associate my local branches to codereview URLs?* + + * `git map-branches -vv` will show your active branches and their status. + * `git cl issue` will reveal the issue URL for the current branch. + * `git cl web` will open that URL in your browser. + + +## Legal stuff + +All contributors must have valid Gerrit/Google accounts (which means you must +be [old enough to manage your own +account](https://support.google.com/accounts/answer/1350409)) and complete the +contributor license agreement. + +For individual contributors, please complete the [Individual Contributor +License Agreement](https://cla.developers.google.com/about/google-individual?csw=1)] online. Corporate contributors must fill out the [Corporate Contributor License +Agreement](https://cla.developers.google.com/about/google-corporate?csw=1) and +send it to us as described on that page. + +### First-time contributors + +Add your or your organization's name and contact info to the [`AUTHORS`](./AUTHORS) +file for Chromium DevTools. Please include this as part of your first patch and +not as a separate standalone patch. + +### External contributor checklist for reviewers + +Before LGTMing a change from a non-`chromium.org` address, ensure that the +contribution can be accepted: + +- Definition: The "author" is the email address that owns the code review + request on +- Ensure the author is already listed in the [`AUTHORS`](./AUTHORS). + In some cases, the author's company might have a wildcard rule + (e.g. `*@google.com`). +- If the author or their company is not listed, the CL should include a new + [`AUTHORS`](./AUTHORS) entry. + - Ensure the new entry is reviewed by a reviewer who works for Google. + - Contributor License Agreement can be verified by Googlers at http://go/cla. + - If there is a corporate CLA for the author's company, it must list the + person explicitly (or the list of authorized contributors must say + something like "All employees"). If the author is not on their company's + roster, do not accept the change. diff --git a/docs/contributing/changes.md b/docs/contributing/changes.md new file mode 100644 index 000000000000..819228fdcd7f --- /dev/null +++ b/docs/contributing/changes.md @@ -0,0 +1,180 @@ +# Contributing changes to Chromium DevTools + +See [Get the Code](../get_the_code.md) for details on how to checkout the code, +and [Design Documents](design.md) for information regarding our design process. +Also check out [Contributing to +Chromium](https://chromium.googlesource.com/chromium/src/+/main/docs/contributing.md) +for general information how to contribute to any Chromium project (including +its developer tools). + +[TOC] + +## Creating a change + +Check out the documentation about [creating a change in Chromium] and [uploading +a change for review in Chromium], what's said in there basically applies to the +`devtools-frontend` repository as well. + +At least two committers need to have been involved in the CL (change list) either +as reviewer or author. See the [committers policy] for more information. + +*** promo +**BEST PRACTICE:** Favor [Small CLs] whenever possible, because they are much +easier to review in general, easier to reason about, and less likely to introduce +bugs. Apply common sense however, and don't take this to the extreme for the +sake of making a CL as small as possible, for example when fixing a bug, land +the actual code change together with the test in one CL. +*** + +### Change descriptions + +In a nutshell, optimize for meaningful CL (change list) descriptions: + +- Provide information on what was changed and why. +- Provide before/after screenshots (if applicable). +- Provide relevant link to demo or example (if applicable). +- Provide link to design doc (if applicable). + +Descriptions for CLs should comply with [Google's Best Practices for good CL +descriptions] and follow the [Chromium-specific CL description tips]. We strive +to have CL descriptions that properly capture both the **what** and the **why** +of the change and ideally make sense on their own: + +- A CL description is a public record of what change is being made and why it + was made. It will become a permanent part of our version control history, + and will possibly be read by hundreds of people other than your reviewers + over the years. +- Future developers will search for your CL based on its description. Someone + in the future might be looking for your change because of a faint memory of + its relevance but without the specifics handy. If all the important + information is in the code and not the description, it's going to be a lot + harder for them to locate your CL. + +Descriptions should be formatted as follows: + +``` +[area] Summary of change (one line) + +Longer description of change addressing as appropriate: why the change +is made, context if it is part of many changes, description of previous +behavior and newly introduced differences, etc. + +Long lines should be wrapped to 72 columns for easier log message +viewing in terminals. + +Bug: 123456 +Fixed: 654321 +Doc: design doc and/or PRD (go/, bit.ly/ or goo.gle/ short link) +Demo: URL of some demo (ideally on devtools-dbg-stories.netlify.app) +Before: URL of screenshot before change +After: URL or screenshot after change +``` + +The individual items here are as follows: + +1. The first line should be a short summary of **what** exactly changed with + this CL. The `[area]` is optional, but strongly encouraged to give an + immediate idea of what's affected (the most) by the change. For example if + you fix a bug in the Sources panel, prefixing the first line with + `[sources]` makes this clear. +1. The description should briefly describe the motivation for the change when + appropriate (the **why**) and then go into a detailed description of + **what** was changed specifically and **how**. You may find yourself + repeating some of the information that is already found in the product + requirements or the design document, but that's fine, because the time + saving later when trying to understand the impact of a CL can be + significant, and also the PRD or DD can evolve and might no longer + appropriately capture the **why** and the **what** for this particular CL. +1. Every CL that lands has to have a `Bug: ` or `Fixed: ` line, + referencing the relevant [crbug(s)](http://crbug.com). + - Since Chromium, DevTools, and V8 have migrated to Buganizer, there's no + need to use an explicit tracker, and we **strongly discourage the use of + any prefixes**, in particular `b:` or `b/` since that creates an + internal link. + - It is possible under rare circumstances to use `Bug: none`, for example + to fix typos or update documentation (outside of the scope of a + project). +1. Every CL that is part of a bigger project should reference a design document + (DD) via the `Doc:` line. It might also reference a product requirements + document (PRD) directly, but that should rarely be the case (instead the DD + should include appropriate references to the PRD). + + For public docs, consider adding a `bit.ly/` or `goo.gle/` short link. + + **Googlers:** Don't forget to create the mandatory + `go/chrome-devtools:-design` short link. For internal docs, + use only the `go/chrome-devtools:-design` short link directly, + for public docs, you can optionally list the `go/` link in addition to the + `bit.ly` or `goo.gle` short link. +1. The `Demo:`, `Before:`, and `After:` lines are primarily there to support + the Developer Advocates and Tech Writers (see + [go/help-document-devtools](http://go/help-document-devtools)). + - The `Demo:` should ideally be pushed to [ChromeDevTools/devtools-dbg-stories] + and will thus be automatically available on [devtools-dbg-stories.netlify.app]. + - For `Before:` and `After:` please link directly to hosted images + (preferably PNGs); these links can be either public services (like + [imgur.com](https://imgur.com)) or hosted internally (on + [screen/](http://screen/)). + +### Creating demos (for repros) + +See the section about [Creating demos for crbugs](https://github.com/ChromeDevTools/devtools-dbg-stories#creating-demos-for-crbugs) +and check out the [README](https://github.com/ChromeDevTools/devtools-dbg-stories#readme) for more information about non-trivial test +cases and the like. + +## Merges and cherry-picks + +_Merge request/approval is handled by Chromium Release Managers. DevTools follows [Chromium's merge criteria](https://chromium.googlesource.com/chromium/src.git/+/refs/heads/main/docs/process/merge_request.md#merge-criteria-phases). In exceptional cases please get in touch with hablich@chromium.org._ + +Step-by-step guide on how to merge: + +1. Request approval to merge by adding the milestone to the `Merge-Request` filed of the relevant crbug. A bot will come by and either ask for more info ([example](http://crbug.com/1123307#c1)) or approve the request. +1. Backmerges are done to the `chromium/xxxx` (e.g. `chromium/3979`) branch on the DevTools frontend repo. + Use or [Omahaproxy](https://omahaproxy.appspot.com/) + to find out what branch a major Chromium version has (column `true_branch`). +1. Open the to-be-merged commit in Gerrit + ([example](https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/1928912)). +1. Click the hamburger menu on the top right and select “Cherry pick”. +1. Select the branch to merge to e.g. `chromium/3968`. +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. Done. + +### Merge conflicts + +If the approach above causes conflicts that need resolving, you can use an alternative git workflow which allows you to resolve conflicts locally before uploading. This is very similar to the [chromium git merge steps](https://chromium.googlesource.com/chromium/src.git/+/refs/heads/main/docs/process/merge_request.md#using-git) but with different branch names. These steps will **create the cherry-pick CL via git**. + +_It is suggested to use the Gerrit UI approach when possible, it is more straightforward and automated. Only use this approach if your cherry-pick causes conflicts._ + +For the commands below, replace `xxxx` with the Chromium branch number that you are merging into. + +To set up your local environment run: + +``` +gclient sync --with_branch_heads +git fetch +git checkout -b BRANCH_NAME origin/chromium/xxxx +git cl upstream origin/chromium/xxxx +``` + +You can then cherry-pick your commit from the main branch: + +``` +git cherry-pick -x YOUR_COMMIT +``` + +You can then resolve any conflicts, run tests, build DevTools, etc, locally to verify everything is working. Then run `git cl upload` to upload the CL and get a review as normal. + +**Make sure you remove the Change-ID: line** from the description to avoid issues when uploading the CL. + + + [creating a change in Chromium]: https://chromium.googlesource.com/chromium/src/+/main/docs/contributing.md#creating-a-change + [uploading a change for review in Chromium]: https://chromium.googlesource.com/chromium/src/+/main/docs/contributing.md#uploading-a-change-for-review + [committers policy]: https://chromium.googlesource.com/devtools/devtools-frontend/+/main/docs/committers_policy.md + [Small CLs]: https://google.github.io/eng-practices/review/developer/small-cls.html + [Google's Best Practices for good CL descriptions]: https://google.github.io/eng-practices/review/developer/cl-descriptions.html + [Chromium-specific CL description tips]: https://chromium.googlesource.com/chromium/src/+/main/docs/contributing.md#Chromium_specific-description-tips + [ChromeDevTools/devtools-dbg-stories]: https://github.com/ChromeDevTools/devtools-dbg-stories + [devtools-dbg-stories.netlify.app]: https://devtools-dbg-stories.netlify.app diff --git a/docs/contributing/design.md b/docs/contributing/design.md new file mode 100644 index 000000000000..6c245d01319d --- /dev/null +++ b/docs/contributing/design.md @@ -0,0 +1,166 @@ +# Design Documents + +**TL;DR**: This document outlines the development process for Chromium DevTools, +in particular the established culture and processes around design artifacts. + +[TOC] + +## Writing a design document + +Any non-trivial technical effort that will significantly impact Chromium DevTools +should have a design doc ([template](https://goo.gle/devtools-design-doc-template)), +sometimes also referred to as _bluedoc_. Specifically, we require design docs +(DDs) in the following cases: + +1. When writing code that will have a large impact on DevTools as a whole, e.g. + when you are changing behavior of a critical component like the Console or + Sources panel. +1. When beginning a large technical undertaking that should be documented for + historical reasons (>1 person-month of work can be used as a general + guideline). + +*** promo +**Tip (Googlers):** +For smaller scale changes or when you are not sure yet whether any of the +criteria above will apply, but you still want to have it written up and +discussed, you can start with a Design Proposal +([template](http://go/chrome-devtools-greendoc-template)). +These should always be Google internal. +*** + +Public design docs have to live in the +[Design Documents](https://drive.google.com/drive/folders/1JbUthATfybvMQR3yAHC4J0P7n6oftYNq) +folder of the shared public +[Chromium DevTools](http://go/chrome-devtools/team-resources#chromium-devtools-shared-drive) team drive, +which automatically makes them commentable for +[contributors@chromium.org](mailto:contributors@chromium.org) and +[devtools-dev@chromium.org](mailto:devtools-dev@chromium.org). And they need to +be send to +[devtools-dev+design@chromium.org](mailto:devtools-dev+design@chromium.org). + +Google internal design docs have to live in the +[Design Documents (internal)](http://go/chrome-devtools:design-internal-drive) +folder of the shared internal +[Chrome DevTools](http://go/chrome-devtools/team-resources#chrome-devtools-shared-drive) team drive, and +should be sent to +[chrome-devtools@google.com](mailto:chrome-devtools@google.com). + +*** note +**IMPORTANT (Googlers):** Every design document (whether public or internal) must be editable +by [chrome-devtools-staff@google.com](mailto:chrome-devtools-staff@google.com) and +must have a `go/chrome-devtools:-design` go/ link pointing to it +(even for publicly visible documents). +*** + +Follow the steps in the +[Chrome DevTools Design Review Guidelines](#Review-Guidelines) +to proceed with your design document and get it reviewed and approved. + +## Review Guidelines + +When contributing to Chrome DevTools, please follow the process explained in this document. This is to reach a clear agreement on proposals, while involving all relevant stakeholders and decision makers. + +This process puts the IC in charge, but also requires Chrome DevTools' leaders to help the IC navigate the decision process. It includes an escalation path in case of disagreement. The overhead of this process should be proportionate to the scope of the proposal. + +**Important:** + +1. Assume good intentions. +1. Be kind and civilized. +1. Be pragmatic. + +![DevTools Design Process](./images/design-guidelines.png) + +### Roles + +#### Individual Contributor (IC) + +_LGTM_: N/A + +This person is the creator of the feature and the creator of the design documentation. + +#### Technical Lead (TL) + +_LGTM_: Required. May delegate. + +The Chrome DevTools TL is Danil Somsikov (dsv@chromium.org). The TL ensures architectural consistency and good coverage by the right set of LGTM providers, and is required to sign off on the design. They may however explicitly delegate to other LGTM providers. + +In the absence of the TL, an EnReOw can act in their stead. + +#### LGTM provider + +_LGTM_: Required. May delegate. + +This is a person that is required to give LGTM. These are usually ICs with significant knowledge about the areas in question. + +#### Reviewer + +_LGTM_: Not required. + +This is somebody who reviews and comments on the proposal. Their input should be considered, although their LGTM is not required. + +#### The Eng Review Owners (EnReOw) + +_LGTM_: Not required. However, LGTM or non-LGTM is binding. + +Stuck proposals can be escalated to the [ENG_REVIEW_OWNERS](https://cs.chromium.org/chromium/src/third_party/devtools-frontend/src/config/owner/ENG_REVIEW_OWNERS). Potential use cases of such an escalation: + +- An LGTM provider is non-responsive. +- No consensus on the design can be reached. + +The EnReOw can overrule non-LGTMs or LGTMs. + +### Detailed workflow + +1. IC shares the document with LGTM providers and reviewers according to the roles listed above. +1. LGTM providers may add more LGTM providers to remove themselves as LGTM providers. +1. LGTM providers and reviewers review the design document and add feedback. +1. IC incorporates feedback and iterates on their design document. +1. Optional: the design doc is shared publicly with devtools-dev+design@chromium.org (make sure to give comment access to contributors@chromium.org, but untick the "Notify" checkbox). +1. IC collects LGTMs by addressing feedback. Iterate if necessary. +1. Once all required LGTMs have been collected, proceed with implementation. +1. On disagreement that cannot be resolved or unreasonable delays, escalate to EnReOw. +1. Implement and iterate on CLs with code owners. We expect the implementation to take place on the public repository's main branch. Note that a series of small incremental changes has a higher chance of receiving timely reviews and actionable feedback. + +## FAQ + +### Is it worth creating a design document? + +It is always useful to have a design document. Its length can vary depending on the scope of the proposed change. + +### When should the design process be kicked off? + +As soon as possible so that a wide range of opinions can be taken into consideration. If you share your idea or prototype at a later stage, you risk having to redo the work because you missed a constraint. + +### How to decide who to add to the list of LGTM providers? + +Some pointers when people should be added to the list of LGTM providers: + +- OWNERs of the source files/directories you anticipate to touch +- Main component expert of the components you anticipate to touch +- Downstream consumers of your changes e.g. when you change an API + +### Where can I find a template for design documents? + +[goo.gle/devtools-design-doc-template](https://goo.gle/devtools-design-doc-template) + +### What if I made big changes to the design document? + +Make sure you still have the LGTMs e.g. by pinging the LGTM providers. + +### LGTM providers do not comment on my design document, what should I do? + +In this case you can follow this path of escalation: + +1. Ping them directly via mail, chat or comment/assignment in the doc and specifically ask them explicitly to add an LGTM or non-LGTM. +1. Get your TL involved and ask them for help. +1. Escalate to EnReOw. + +### Somebody added me as an LGTM provider to a doc, what should I do? + +Review the design document. If you think there are other people who should take a look, add them as LGTM providers or as reviewers. If you don't think you are the right person, remove yourself as LGTM provider. + +If you agree with the design, add an LGTM to the table. If you have blocking concerns, add "Not LGTM, because " to the table. Be prepared to re-review the design after another iteration. + +### How does this work together with the Blink Intents process? + +The Chromium DevTools Design Review Guidelines complement [Chromium’s feature launch process](https://www.chromium.org/blink/launching-features). If you are launching a new Web platform feature, please follow the Chromium launch process. It likely makes sense to have all the LGTMs gathered at the point in time you would send an Intent to Implement. diff --git a/docs/contributing/images/design-guidelines.png b/docs/contributing/images/design-guidelines.png new file mode 100644 index 000000000000..865474fc38eb Binary files /dev/null and b/docs/contributing/images/design-guidelines.png differ diff --git a/docs/contributing/images/issues-nearestslo.png b/docs/contributing/images/issues-nearestslo.png new file mode 100644 index 000000000000..f60f6b646920 Binary files /dev/null and b/docs/contributing/images/issues-nearestslo.png differ diff --git a/docs/contributing/images/issues-report-a-devtools-issue.png b/docs/contributing/images/issues-report-a-devtools-issue.png new file mode 100644 index 000000000000..a4ca982a01bc Binary files /dev/null and b/docs/contributing/images/issues-report-a-devtools-issue.png differ diff --git a/docs/contributing/images/issues-report-template.png b/docs/contributing/images/issues-report-template.png new file mode 100644 index 000000000000..5f548ef70c2b Binary files /dev/null and b/docs/contributing/images/issues-report-template.png differ diff --git a/docs/contributing/images/issues-slo-reports-settings.png b/docs/contributing/images/issues-slo-reports-settings.png new file mode 100644 index 000000000000..c08b3867fcce Binary files /dev/null and b/docs/contributing/images/issues-slo-reports-settings.png differ diff --git a/docs/contributing/images/quickstart-gerrit-reviewers.png b/docs/contributing/images/quickstart-gerrit-reviewers.png new file mode 100644 index 000000000000..be478c2f4397 Binary files /dev/null and b/docs/contributing/images/quickstart-gerrit-reviewers.png differ diff --git a/docs/contributing/images/quickstart-inception.png b/docs/contributing/images/quickstart-inception.png new file mode 100644 index 000000000000..1cac4e3538eb Binary files /dev/null and b/docs/contributing/images/quickstart-inception.png differ diff --git a/docs/contributing/issues.md b/docs/contributing/issues.md new file mode 100644 index 000000000000..1282190f28a1 --- /dev/null +++ b/docs/contributing/issues.md @@ -0,0 +1,270 @@ +# Chromium DevTools Issues Guidelines + +[goo.gle/chromium-devtools-issues](https://goo.gle/chromium-devtools-issues) + +This document explains how Chromium DevTools (related) issues are tracked in the +`Chromium>Platform>DevTools` component tree of [crbug], how we define and manage +priorities and Service Level Objectives (SLOs), as well as the overall bug life +cycle. + +[TOC] + +In 2024 the Chromium project migrated [crbug] to the [Google Issue Tracker], called +[Buganizer] internally. While most of the functionality is generally available +to all Chromium contributors, some of it is limited to Googlers, and can only +be accessed via [Buganizer] internally. + +## Bug reporting guidelines + +The process for reporting a bug in Chromium DevTools follows the Chromium-wide +[Bug Life Cycle and Reporting Guidelines], and we encourage you to first read +through the [How to file a good browser bug] article. Proceed according to the +check list below: + +1. Try to verify that it is indeed a bug and not the intended behavior of a + certain feature. +1. Check if there is already a bug report for it, by searching in the list of + [Open Chromium DevTools Bugs]. If you find an existing bug report, click + the **+1** button in the upper-right corner of the page to indicate that + you are also affected by this. +1. If there's no existing bug report that matches your issue, start reporting + a new bug. + +### Report the bug + +You can use the shortlink [goo.gle/devtools-bug] or the **Help > Report a +DevTools issue** menu item to start a new bug report. + +![Report a DevTools Issues](./images/issues-report-a-devtools-issue.png) + +You might need to login to the [Google Issue Tracker] first with a Google +account in order to proceed from there. Afterwards the **Defect from user** +template opens, where you can describe the bug. Note that the template defaults +to Markdown (with a preview below the text input box). + +![Create Issue Template](./images/issues-report-template.png) + +1. Please enter a meaningful title. +1. Replace `` and `` with the relevant + version information. +1. Outline exact steps to reproduce the problem. Make sure to provide steps + that are easy and accessible. Ideally create a minified test case on + [glitch.com](http://glitch.com) or [GitHub](http://github.com). Also + make sure to include screenshots and videos that help us to reproduce + and understand the problem you are facing. + +## Overview + +Check out the [Issues Overview] for a general introduction to the [Google Issue +Tracker]. This section provides an overview of the Chromium DevTools specifics. + +### Issue types + +[crbug] supports a wide range of different issue types, with ambiguous semantics. +For Chromium DevTools we explicitly limit the set of types we use and give them +well-defined semantics: + +| Issue Type | Meaning | +| -------------------- | ------------------------------------------ | +| **Bug** | The behavior does not match what is supposed to occur or what is documented. The product does not work as expected. | +| **Feature Request** | The product works as intended but could be improved. | +| **Internal Cleanup** | This is typically a maintenance issue. The issue has no effect on the behavior of a product, but addressing it may allow more intuitive interaction. | +| **Vulnerability** | Security vulnerabilities subject to the handling outlined in Google's [Vulnerability Priority Guidelines](http://go/vulnerability-slo). | +| **Privacy Issue** | Privacy issues subject to the handling outlined in Google's [Privacy Issue Bugs](http://go/pib-slo). | +| **Task** | A small unit of work. | +| **Project** | A goal-driven effort with a finite start and end, focused on creating a unique product, service, or result. | +| **Feature** | A collection of work that provides a specific value to the user. | + +The first 6 (**Bug** to **Task**) are used for day-to-day work and for issues +reported by users. The last 2 (**Project** and **Feature**) are used to organize +the other types of issues for the purpose of planning (ahead). We explicitly +don't use Customer Issue, Process, Milestone, Epic, and Story within Chrome DevTools. + +*** promo +**BEST PRACTICE:** Limit the nesting of **Project** and **Feature** to the bare +minimum needed, and use **Task** for small chunks of work. +*** + +### Parent-Child Relationships and Blocking + +*** note +**TL;DR:** + +- Prefer parent-child relationships to split work into smaller chunks. +- Prefer blocking to express dependencies between independent / adjacent +issues. +*** + +When splitting up work into smaller chunks or when scoping a project that +encompasses multiple bugs or feature requests, favor to express this via a +parent-child relationship. Consider the example of a CSS Nesting: + +1. This should start with an issue of type Feature which is about adding CSS + Nesting support to Chromium DevTools. +1. This Feature has child issues of type Task, which are concerned with adding + CSS Nesting support to the various parts of DevTools involved, for example + the CDP (Chrome DevTools Protocol), the Elements panel, the Sources panel, + and so forth. +1. Over the course of the project there'll likely also be Feature Requests and + Bugs from internal and external developers, which should also be parented + under the CSS Nesting Feature issue. + +### Priorities + +Below is a table to guide how to think about priorities, aligned with Chromium's +[Triage Best Practices]: + +| Priority | Timeline | Description | +| ----------------------------------------- | ------------------------------ | --------------------------------------- | +| `P0`
**(emergency)** | Requires immediate resolution. | Regressions which are substantially impacting existing users, partners, or developers.
High-risk security issues affecting the stable channel.
Situations that create large, urgent, legal or financial risks for Google. +| `P1`
**(priority engineering work)** | Needed for target milestone. | Major Regressions.
Work requiring prompt resolution.
Work that has to get done before the targeted release. +| `P2`
**(active engineering work)** | Wanted for target milestone. | Non-urgent issues.
Important issues that are worked on as best effort, without a milestone.
Polish or bug fixing work in areas where the team has decided we want to invest. +| `P3`
**(later, want to do)** | Not time sensitive. | Something we want to do, but not right now.
Legitimate issues that we will work on when we have the cycles to do so. +| `P4`
**(later, maybe never)** | Some day... or never. | Nice to have, but also fine not to have. + +### Components + +The following components in [crbug] are owned by the Chrome DevTools team. + +| Component | Description | +| -------------------------------------------------------- | ------------------------------------------------------------- | +| `Chromium>Platform>DevTools` | Issues that don't fit any specific category | +| `Chromium>Platform>DevTools>Accessibility` | DevTools' accessibility | +| `Chromium>Platform>DevTools>AI` | Console Insights and AI Assistance panel | +| `Chromium>Platform>DevTools>Animations` | Animations panel | +| `Chromium>Platform>DevTools>Application` | Application panel | +| `Chromium>Platform>DevTools>Browser Automation` | Browser Automation issues | +| `Chromium>Platform>DevTools>Browser Automation>Headless` | Chrome Headless issues | +| `Chromium>Platform>DevTools>Console` | Console panel | +| `Chromium>Platform>DevTools>Elements` | Elements panel | +| `Chromium>Platform>DevTools>Infra` | Issues related to DevTools' infrastructure | +| `Chromium>Platform>DevTools>Issues` | Issues panel | +| `Chromium>Platform>DevTools>Lighthouse` | Lighthouse panel | +| `Chromium>Platform>DevTools>Memory` | Heap/Memory Profiling, Memory Analysis | +| `Chromium>Platform>DevTools>Mobile` | Mobile Emulation / Debugging | +| `Chromium>Platform>DevTools>Network` | Network, Network conditions, Network request blocking panels | +| `Chromium>Platform>DevTools>Performance` | Performance, Performance Monitor, Performance Insights panels | +| `Chromium>Platform>DevTools>Extensions` | Issues related to DevTools extensions and extensibility | +| `Chromium>Platform>DevTools>Recorder` | Recorder panel | +| `Chromium>Platform>DevTools>Security` | Security panel | +| `Chromium>Platform>DevTools>Sources` | Sources panel | +| `Chromium>Platform>DevTools>UX` | Usability and interface issues | +| `Chromium>Platform>DevTools>WebAssembly` | WebAssembly issues | + +### Hotlists + +The [Chrome DevTools TaskFlow Hotlists] bookmark group contains all the hotlists +relevant to issue management for Chromium DevTools (in particular via the Google +internal Chrome DevTools [TaskFlow]). + +In particular we use the following Chromium-wide hotlists. + +| Hotlist | Description +| -------------------------------------------------- | ----------- +| [`Chromium-Regression`](http://issues.chromium.org/hotlists/5438261) | Hotlist used to track user-noticeable regressions across Chromium. +| [`Needs-Feedback`](http://issues.chromium.org/hotlists/5433459) | Used by the TEs and the [Triage Gardeners](triage-gardener.md) to request more feedback on an issue. The [Chrome Blintz service](http://go/chrome-blintz-user-guide) will automatically remove the label once the reporter provides more feedback. +| [`TE-NeedsTriageHelp`](http://issues.chromium.org/hotlists/5681652) | Used by TEs when they cannot confirm a new issue and request help from the engineering team. +| [`Unconfirmed`](http://issues.chromium.org/hotlists/5437934) | All user reported issue start their life on this hotlist. TEs do a first level triage and try to reproduce the problem, and afterwards either close the issue, or remove it from this hotlist, and therefore forward it to our [TaskFlow Inbox]. +| [`User-Submitted`](http://issues.chromium.org/hotlists/5562135) | Part of the `DevTools Issue` template, all user reported issues start life on this hotlist. + +*** note +**Note**: We don't actively monitor or utilize the +[`Available`](http://issues.chromium.org/hotlists/5438642) hotlist, however, +meaning that we aren't fully aligned with the [Chromium-wide triage guidelines]. +In particular, for Chromium-wide dashboards that utilize +[`Available`](http://issues.chromium.org/hotlists/5438642) as an indicator for +the triage status, Chromium DevTools might show up with a high percentage of +untriaged issues due to this fact. +*** + +### T-Shirt Sizes + +We use the T-Shirt sizes approach to estimate effort for the `Chromium>Platform>DevTools` +component tree, based on the following guidelines: + +| Size | Description | Examples | +| :--- | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| S | Small CL | [Styles bar loses focus in Chrome OS DevTools](http://crbug.com/338348417), [Add 20x CPU throttling preset](https://crbug.com/324978881), [Remove 'Consistent source map variable experiment'](http://crbug.com/40944633), [Autofill tab breaks with phone numbers starting with '+'](https://b.corp.google.com/issues/335409093) | +| M | Medium-sized CL or series of trivial CLs | [Local overrides for New Tab Page misses one "/" in folder name](http://crbug.com/328210785), [Memory tool should highlight common problems and opportunities](http://crbug.com/337094903), [Improve the developer experience of using compression dictionaries](http://crbug.com/333756098) | +| L | Large-sized CL or series of non-trivial CLs | [Excluding sensitive data from HARs (HTTP Archives) by default](https://crbug.com/361717594), [Exceptions in promise constructor should be treated as promise rejection](http://crbug.com/40283985) | +| XL | quarter-long single-person or larger project | [Performance Insights](http://crbug.com/40810111), [Replace regex-matching in the StylesSidebarPane](http://crbug.com/40945390), [MPArch migration](http://crbug.com/40238399), [GM3 adoption](http://crbug.com/40273199) | + +## SLOs + +In order to deliver a better product experience for developers using Chromium +DevTools we want to + +1. reduce the number of regressions that ship to the (Chrome) Stable channel, and +2. reduce the number of bugs overall. + +The following SLOs (Service Level Objectives) apply to issues of type Bug, +Vulnerability, and Privacy Issue. other types of issues such as Feature Request +or Task are out of scope for SLOs (with the notable exception of Postmortem action +items, where Chrome also enforces SLOs for non-bug issues). We also explicitly +restrict these SLOs to bugs in [crbug], and are not concerned with bugs that are +tracked in other places such as GitHub. Below is a high level summary of our SLOs +(Googlers can check the [Chrome DevTools SLO Policy] and [Chrome SLO Policy] for +more details): + +| | Assignment | Response | Closure +| ---- | -------------- | ------------------ | -------- +| `P0` | 1 business day | Every business day | 1 week +| `P1` | 1 week | 1 week | 4 weeks +| `P2` | 2 months | - | 6 months +| `P3` | 1 year | - | - + +The first two rows are identical to [go/chrome-slo], with the last two rows being +specific to Chrome DevTools. [crbug] provides a **Nearest SLO** column that +surfaces SLO violations easily: + +![Nearest SLO in crbug](./images/issues-nearestslo.png "Nearest SLO in crbug") + +- [SLO violations for Chrome DevTools](https://issues.chromium.org/issues?q=status:open%20componentid:1457055%2B%20type:(bug%7Cvulnerability%7Cprivacy_issue)%20nearestslo:10000d) + + +### Release Blocking Issues + +In accordance with go/chrome-slo there are special SLOs for issues that are +severe enough to block a release shipping to users (see [go/chrome-release-slos]). +They apply to bug types in the same way as the above SLOs. + +| | Assignment | Response | Closure +| ------------------------------------------------------------------ | ---------- | ------------ | ------- +| [Urgent](http://go/chrome-release-slos#bookmark=id.2wgnoi9mltcx) | 1 day | Every day | 2 days +| [Standard](http://go/chrome-release-slos#bookmark=id.bksmb4ip8mav) | 2 days | Every 2 days | 10 days + +### Email Reports + +_Googlers only:_ [Buganizer] provides a nice feature that allows you to subscribe to +[Email Reports](http://go/buganizer/guides/slo-reporting#email-reports) for your +SLO (violations). Just go to **Settings** in Buganizer and enable **Subscribe to +your own reports** under **SLO Reports**. + +![Subscribe to SLO Email Reports](./images/issues-slo-reports-settings.png "Subscribe to SLO Email Reports") + +This will get you a daily email (or whichever cadence you prefer) from Buganizer +in your Inbox that shows you up to 25 P0 and P1 out-of-SLO issues. + +### Dashboard + +_Googlers only:_ You can use the [Buganizer SLO Compliance] dashboard, which is +refreshed every 2-4 hours, to see SLO compliance for a given lead. + + [crbug]: https://crbug.com + [Google Issue Tracker]: https://issuetracker.google.com/ + [Buganizer]: http://buganizer/ + [Issues Overview]: https://developers.google.com/issue-tracker/concepts/issues + [Chrome DevTools TaskFlow Hotlists]: https://issues.chromium.org/bookmark-groups/895270 + [Chromium-wide triage guidelines]: https://www.chromium.org/for-testers/bug-reporting-guidelines/#bug-life-cycle + [Triage Best Practices]: https://www.chromium.org/for-testers/bug-reporting-guidelines/triage-best-practices + [Bug Life Cycle and Reporting Guidelines]: https://www.chromium.org/for-testers/bug-reporting-guidelines + [How to file a good browser bug]: https://web.dev/articles/how-to-file-a-good-bug + [Open Chromium DevTools Bugs]: https://issues.chromium.org/issues?q=status:open%20componentid:1457055%2B%20type:bug + [goo.gle/devtools-bug]: https://goo.gle/devtools-bug + [Chrome DevTools SLO Policy]: https://b.corp.google.com/slos/61348 + [Chrome SLO Policy]: https://b.corp.google.com/slos/1834 + [go/chrome-slo]: http://go/chrome-slo + [go/chrome-release-slos]: http://go/chrome-release-slos + [Buganizer SLO Compliance]: go/b-slo-compliance + [TaskFlow]: http://go/chrome-devtools:taskflow + [TaskFlow Inbox]: http://go/chrome-devtools:taskflow/inbox diff --git a/docs/contributing/navbar.md b/docs/contributing/navbar.md new file mode 100644 index 000000000000..6abb5887dc12 --- /dev/null +++ b/docs/contributing/navbar.md @@ -0,0 +1,8 @@ +# Chromium DevTools Contribution Guide + +[logo]: https://github.com/ChromeDevTools/devtools-logo/raw/master/logos/png/devtools-circle-48.png +[home]: README.md +[devtools]: ../README.md + +* [Chromium DevTools Contribution Guide][home] +* [Chromium DevTools Documentation][devtools] diff --git a/docs/contributing/settings-experiments-features.md b/docs/contributing/settings-experiments-features.md new file mode 100644 index 000000000000..f64c6ce8e8b6 --- /dev/null +++ b/docs/contributing/settings-experiments-features.md @@ -0,0 +1,155 @@ +# Settings, Experiments, and Features in Chromium DevTools + +From a developers perspective the Chromium DevTools experience can be +customized in multiple ways: + +* via Settings \> Preferences, +* via Settings \> Experiments, +* via `chrome://flags`, +* or by passing a command line flag to Chromium. + +Adding new DevTools experiments is deprecated, the preferred way for adding new +features / exposing experimental features is via `base::Feature`s. These are +controllable via Chromium command line parameters or optionally via `chrome://flags`. + + +[TOC] + +## How to add `base::Feature` feature flags + +[go/chrome-devtools:command-line-config](http://go/chrome-devtools:command-line-config) + +`base::Feature`s are defined in the Chromium repository and made available to +DevTools via host bindings. This allows configuring features which have both a +DevTools front-end and a Chromium back-end component from a single source of +truth. But front-end-only features can be controlled via a `base::Feature` just +as well. + +By default, `base::Feature`s are configurable via command line parameters when +launching Chromium. Optionally, they can be made available via the `chrome://flags` +UI as well. + +### Define a new `base::Feature` + +Add a new `base::Feature` to DevTools' [`features.cc`](https://crsrc.org/c/chrome/browser/devtools/features.cc). This feature will automatically be available as a Chrome command line parameter: + +```cxx +// in browser_features.cc + +BASE_FEATURE(kDevToolsNewFeature, "DevToolsNewFeature", + base::FEATURE_DISABLED_BY_DEFAULT); + +// Optionally add feature parameters +const base::FeatureParam kDevToolsNewFeatureStringParam{ + &kDevToolsNewFeature, "string_param", /*default_value=*/""}; +const base::FeatureParam kDevToolsNewFeatureDoubleParam{ + &kDevToolsNewFeature, "double_param", /*default_value=*/0}; + +``` + +Start Chrome via command line including flags: + +``` +out/Default/chrome --enable-features=DevToolsNewFeature +``` + +You can even pass additional feature parameters: + +``` +out/Default/chrome --enable-features="DevToolsNewFeature:string_param/foo/double_param/0.5" +``` + +### Make the `base::Feature` available via `chrome://flags` + +This step is optional. If you want the `base::Feature` to be controllable via the `chrome://flags` UI and not only via the command line, follow [this documentation](https://chromium.googlesource.com/chromium/src/+/main/docs/how_to_add_your_feature_flag.md#step-2_adding-the-feature-flag-to-the-chrome_flags-ui). + +### Add the new feature to the host configuration being sent to DevTools + + Add the new feature to `DevToolsUIBindings::GetHostConfig` ([link to code](https://crsrc.org/c/chrome/browser/devtools/devtools_ui_bindings.cc;l=1506;drc=dd0b2a0bee86088ec0d481bd8722c06edaaba4a4), [example CL](https://crrev.com/c/5625935)). + +### In DevTools, use the new property added to HostConfig + +* Update the type definition in [`Runtime.ts`](https://crsrc.org/c/third_party/devtools-frontend/src/front_end/core/root/Runtime.ts). +* Update the dummy value returned by `getHostConfig` in [`InspectorFrontendHost.ts`](https://crsrc.org/c/third_party/devtools-frontend/src/front_end/core/host/InspectorFrontendHost.ts). +* Access the host config via `Root.Runtime.hostConfig`. +* In unit tests, make sure to assign the expected configuration using `updateHostConfig({ foo: bar })`. + +Please refer to this [example CL](https://crrev.com/c/5626314). + +## How to add experiments + +Note: Adding new DevTools experiments is deprecated, please use a `base::Feature` instead. + +If you want to launch a new feature in DevTools behind an experiment flag, you +will need to do two things: + +1. Make Chromium aware of the experiment and enable it to track users + enabling/disabling the experiment. +2. Register the experiment in DevTools to have it added to the Settings UI. + +### Chromium + +In Chromium, edit `tools/metrics/histograms/enums.xml`. Find the enum titled +`DevToolsExperiments` (your best bet is to search for this text in your editor, +as `enums.xml` is very large). + +Go to the end of this enum, and add a new entry. Make sure that the `value` is +increased by one from the previous entry. The label can be anything you like but +make sure it is easily identifiable. + +```xml + +``` + +See an example Chromium CL [here](https://crrev.com/c/4915777). + +### DevTools front-end + +In DevTools, you need to register the experiment. This is done in +`front_end/entrypoints/main/MainImpl.ts` and is done by calling +`Root.Runtime.experiments.register`: + +```ts +Root.Runtime.experiments.register( + 'yourExperimentNameHere', + 'User facing short description of experiment here', + false); +``` + +The first argument is the experiment's label, and **this must match the label +you used in your Chromium CL**. + +The second argument is a short description of the experiment. This string will +be shown to users. + +Finally, the third argument marks the experiment as unstable. You should pass +`true` if you want your experiment to be marked as unstable. This moves it into +a separate part of the UI where users are warned that enabling the experiment +may cause issues. + +You may also pass in two additional arguments which can be used to link users to +documentation and a way to provide feedback: + +```ts +Root.Runtime.experiments.register( + 'jsProfilerTemporarilyEnable', + 'Enable JavaScript Profiler temporarily', + /* unstable= */ false, + /* documentation */ 'https://goo.gle/js-profiler-deprecation', + /* feedback */ 'https://crbug.com/1354548' +); +``` + +You must also add the experiment to `front_end/core/host/UserMetrics.ts`. Add an +entry to the `DevToolsExperiments` enum, using **the same label and integer +value** that you used in the Chromium CL. You should also increase the +`MaxValue` entry by one. + +Once the experiment is registered, you can check if it is enabled and use this +to run certain code blocks conditionally: + +```ts +if(Root.Runtime.experiments.isEnabled('yourExperimentNameHere')) { + // Experiment code here +} +``` diff --git a/docs/contributing_changes.md b/docs/contributing_changes.md index d57d78cb1c33..cb0b17f309b9 100644 --- a/docs/contributing_changes.md +++ b/docs/contributing_changes.md @@ -1,88 +1 @@ -# Contributing changes to Chromium DevTools - -See [Get the Code](get_the_code.md) for details on how to checkout the code, and [Chrome DevTools Design Review Guidelines](design_guidelines.md) for -information regarding our design process. - -[TOC] - -## Creating a change - -Usual [steps](https://chromium.googlesource.com/chromium/src/+/main/docs/contributing.md#creating-a-change) for creating a change work out of the box, when executed in the DevTools frontend repository. - -Tips to create meaningful CL descriptions: -- Provide information on what was changed and why -- Provide before/after screenshots (if applicable) -- Provide relevant link to demo or example (if applicable) -- Provide link to design doc (if applicable) - -At least two committers need to have been involved in the CL either as reviewer or author. See [committers policy](https://chromium.googlesource.com/devtools/devtools-frontend/+/main/docs/committers_policy.md) for more information. - -Example CL, adapted from [Chromium guidelines](https://chromium.googlesource.com/chromium/src/+/main/docs/contributing.md#uploading-a-change-for-review): - -``` -Summary of change (one line) - -Longer description of change addressing as appropriate: -what change was made, why the change is made, context if -it is part of many changes, description of previous behavior -and newly introduced differences, etc. - -Long lines should be wrapped to 72 columns for easier log message -viewing in terminals. - -How to test: - 1. .. - 2. .. - -Before: https://page-to-before-screenshot.com/before -After: https://page-to-after-screenshot.com/after -Bug: 123456 - -``` -## Merges and cherry-picks - -_Merge request/approval is handled by Chromium Release Managers. DevTools follows [Chromium's merge criteria](https://chromium.googlesource.com/chromium/src.git/+/refs/heads/main/docs/process/merge_request.md#merge-criteria-phases). In exceptional cases please get in touch with hablich@chromium.org._ - -Step-by-step guide on how to merge: - -1. Request approval to merge by adding the `Merge-Request-XX` label to the relevant crbug. A bot will come by and either ask for more info ([example](https://bugs.chromium.org/p/chromium/issues/detail?id=1123307#c1)) or approve the request. -1. Backmerges are done to the `chromium/xxxx` (e.g. `chromium/3979`) branch on the DevTools frontend repo. - Use or [Omahaproxy](https://omahaproxy.appspot.com/) - to find out what branch a major Chromium version has (column `true_branch`). -1. Open the to-be-merged commit in Gerrit - ([example](https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/1928912)). -1. Click the hamburger menu on the top right and select “Cherry pick”. -1. Select the branch to merge to e.g. `chromium/3968`. -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. Done. - -### Merge conflicts - -If the approach above causes conflicts that need resolving, you can use an alternative git workflow which allows you to resolve conflicts locally before uploading. This is very similar to the [chromium git merge steps](https://chromium.googlesource.com/chromium/src.git/+/refs/heads/main/docs/process/merge_request.md#using-git) but with different branch names. These steps will **create the cherry-pick CL via git**. - -_It is suggested to use the Gerrit UI approach when possible, it is more straightforward and automated. Only use this approach if your cherry-pick causes conflicts._ - -For the commands below, replace `xxxx` with the Chromium branch number that you are merging into. - -To set up your local environment run: - -``` -gclient sync --with_branch_heads -git fetch -git checkout -b BRANCH_NAME origin/chromium/xxxx -git cl upstream origin/chromium/xxxx -``` - -You can then cherry-pick your commit from the main branch: - -``` -git cherry-pick -x YOUR_COMMIT -``` - -You can then resolve any conflicts, run tests, build DevTools, etc, locally to verify everything is working. Then run `git cl upload` to upload the CL and get a review as normal. - -**Make sure you remove the Change-ID: line** from the description to avoid issues when uploading the CL. - +This file has moved [here](./contributing/changes.md). diff --git a/docs/cookbook/README.md b/docs/cookbook/README.md new file mode 100644 index 000000000000..3a09214070c1 --- /dev/null +++ b/docs/cookbook/README.md @@ -0,0 +1,13 @@ +# Chromium DevTools Cookbook + +[goo.gle/devtools-cookbook](http://goo.gle/devtools-cookbook) + +The cookbook provides *recipes* for common workflows / tasks during development +of Chromium DevTools itself. + +* [Create new Issues in DevTools](create_new_issues.md) +* [Dependencies](dependencies.md) +* [Localization](localization.md) +* [Release Management](release_management.md) +* [UMA metrics in DevTools](uma_metrics.md) +* [DevTools-on-DevTools (aka Debugging the Debugger)](devtools_on_devtools.md) \ No newline at end of file diff --git a/docs/cookbook/create_new_issues.md b/docs/cookbook/create_new_issues.md new file mode 100644 index 000000000000..4c80fd3af218 --- /dev/null +++ b/docs/cookbook/create_new_issues.md @@ -0,0 +1,91 @@ +# Create new Issues in DevTools + +[TOC] + +The goal of this doc is to guide you through the necessary steps to send +messages to the new +[Issues panel](https://developers.google.com/web/updates/2020/05/devtools#issues) +([Design Doc](https://docs.google.com/document/u/1/d/1F6R5Bpb3qHNzGPNBSXwEJ_eP8L-anIj0WinxOIyAh54)). +This will help reduce the console fatigue and will give more context to +developers on what the problem is, why it should be fixed and how it can be +fixed. + +## Why the Issues Panel? + +If there is an existing console log that for some reason you want to edit, this +is a good opportunity to re-think how actionable this message is for developers. +If you are working on a feature and you have in mind throwing a new console log +to notify developers of an unexpected behavior, think about showing an Issue +instead. + +Developers could be missing your warning due to the clutter in the console +caused by the many different messages. By creating a new Issue type, you will +give more context on the problem and make the debugging experience more +actionable for them. + +## Create new or move existing console messages to the Issues panel + +To do so, follow the next steps: + +* Reach-out to [dsv@](mailto:dsv@chromium.org) (DevTools TL) and share the + related design doc. Every Issue should be actionable and have at least one + straightforward solution. With the addition of more context and external + documentation, it will support the developer across the whole debugging + story, making the message more actionable than in the console. +* Pipe your message into DevTools. First you need to decide which additional + information you want to send with your issue. Depending on the answer + you'll have two options: + 1) Use the [generic issue](https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/public/devtools_protocol/browser_protocol.pdl;l=807-829;drc=3e4a3b72cdd0cab0224292a7322ff3cf0248d307). This is the easier option. + All that is required is to add a new value to `GenericIssueErrorType`. + Generic issue allows sending along some pre-defined additional information: + Frame ids, network requests and DOM node ids among others. + 2) If a generic issue is not enough, you can introduce a domain/problem + specific issue type. See [here](https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/public/devtools_protocol/browser_protocol.pdl;l=666;drc=bc268cf81e62349e0f283107d70a5f742476ef4e) + how other issues are defined. You need to add an issue code and an issue + details definition. The issue details should hold all the information + that is required for reporting the issue in the front-end. +* Next, you need to figure out where to report the issue. + Issues can be reported on the browser side (choose this if the + issue is raised in content/browser and/or has information that should not be + shared with the renderer). Otherwise you can report it in the renderer. + * For Browser-side reporting, use + [`devtools_instrumentation::ReportBrowserInitiatedIssue`](https://source.chromium.org/chromium/chromium/src/+/main:content/browser/devtools/devtools_instrumentation.cc;l=1981;drc=10c26d0d230900f91d239f2fe0b731b054127e89) + to report the issue. + * For renderer-side reporting, use an `AddInspectorIssue` method, those + are available at every execution context, plus some more classes. + ([example](https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/bindings/core/v8/isolated_world_csp.cc;l=107;drc=d2b5c17eff35da6ebff8ba20c99688b87e1bc752)). +* Depending on where the issue is reported, creating the protocol structures + works differently. + * An example of how to create the data-structure can be found + * [here](https://source.chromium.org/chromium/chromium/src/+/3564e4bcc7d53aa60350794fc1348792cc33c80d:content/browser/devtools/devtools_instrumentation.cc;drc=d6edf4bb211798b0aa0b656dfb06614cfea043e3;l=181) + for the browser side + * [here](https://source.chromium.org/chromium/chromium/src/+/3564e4bcc7d53aa60350794fc1348792cc33c80d:third_party/blink/renderer/core/inspector/inspector_audits_agent.cc;drc=2decd986a617ab2556ac268e4c2ef156ac8f7361;l=431) + for the renderer side +* Please add the corresponding backend and frontend test for your changes. + * [Example](https://chromium-review.googlesource.com/c/chromium/src/+/2485937) + of a CL introducing backend web\_tests. + * [Example](https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/2485086) + of a CL introducing frontend E2E tests. +* Please CC [szuend@](mailto:szuend@chromium.org) in your CL, and/or add them + as reviewers. You should aim at landing your CL at least 2 weeks before the + Branch cut. Feel free to send out the CL even if it is in an early stage. + The DevTools team can point you in the right direction, and this will avoid + last minute surprises. +* Draft the issue strings (find a template below) and share them with + [dsv@](mailto:dsv@chromium.org) and the rest of your team for approval. +* Once the issue strings are reviewed, implement the front-end CL following + [this example](https://crrev.com/c/2308536). Please add + [szuend@](mailto:szuend@chromium.org) as reviewers to your CL, and send it + out early to get quick feedback. We are happy to help you iterate. +* Please add UMA tracking for your new issue types. This is as easy as adding + the issue types to an enum + ([frontend example CL](https://crrev.com/c/2692913), + [backend example CL](https://crrev.com/c/2694408)). + +## Draft Issue strings + +To create the UX strings the best approach is to draft an initial proposal and +then share it with the broader team for polishing +([existing issue descriptions](https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/issues/descriptions/) +for reference). You can wordsmith the issue description in a separate docs or +directly in the CL with Gerrit. diff --git a/docs/cookbook/dependencies.md b/docs/cookbook/dependencies.md new file mode 100644 index 000000000000..7304e8d36ac9 --- /dev/null +++ b/docs/cookbook/dependencies.md @@ -0,0 +1,103 @@ +# Dependencies + +[TOC] + +## Managing dependencies + +If you need to manually roll a git dependency, it's not sufficient to update the +revision in the DEPS file. Instead, use the gclient tool: `bash gclient setdep +-r DEP@REV # for example build@afe0125ef9e10b400d9ec145aa18fca932369346` This +will simultaneously update both the DEPS entry as well as the gitlink entry for +the corresponding git submodule. + +To sync dependencies from Chromium to DevTools frontend, use +`scripts/deps/roll_deps.py`. Note that this may: - Introduce unneeded +whitespace/formatting changes. Presubmit scripts (e.g. invoked via `git cl +upload`) will automatically fix these locally, so just apply the changes +directly to your change (e.g. with `git commit --amend`) afterwards. - Introduce +breaking changes to the devtools protocol, causing compilation failures. +Unfortunately these need to be handled manually as there are some changes (e.g. +removing an enum value) that cannot fail gracefully. + +The following scripts run as AutoRollers, but can be manually invoked if +desired: + +- To roll the `HEAD` commit of DevTools frontend into Chromium, use + `scripts/deps/roll_to_chromium.py`. +- To update DevTools frontend's DEPS, use `roll-dep`. + +## Third-party Guidelines + +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 `package.json` 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. + +[npm]: https://www.npmjs.com/ +[Chromium third-party guidelines]: https://chromium.googlesource.com/chromium/src/+/HEAD/docs/adding_to_third_party.md +[GN]: https://gn.googlesource.com/gn/+/master/docs/reference.md +[clang-format]: https://clang.llvm.org/docs/ClangFormat.html diff --git a/docs/cookbook/devtools_on_devtools.md b/docs/cookbook/devtools_on_devtools.md new file mode 100644 index 000000000000..ad4f662d8b66 --- /dev/null +++ b/docs/cookbook/devtools_on_devtools.md @@ -0,0 +1,77 @@ +# DevTools-on-DevTools (aka Debugging the Debugger) + +[goo.gle/devtools-on-devtools][self-link] + +The Chromium DevTools front-end is a web application (with some special powers), +and can therefore be debugged like any other web application (using Chromium +DevTools itself). + +## Inspecting the inspector + +You don't need a special build of Chromium or DevTools, you can try this with +any Chrome or Chromium build. Open DevTools on any page, e.g. +`http://www.example.com`, and undock DevTools into a dedicated window. + +![](./images/devtools_on_devtools_starter.png) + +Then in the undocked DevTools window press Cmd+Shift+I (on macOS) or +Ctrl+Shift+I (on Windows, Linux, or Chrome OS), and a new DevTools window will +open, that is debugging the actual DevTools window. You can tell them apart +based on their window titles, the original one says *"DevTools - +www.example.com"*, while the DevTools-on-DevTools says something like +*"DevTools - devtools://devtools/bundled/devtools_app.html"*. + +**Pro-Tip**: Set a different color theme for the DevTools-on-DevTools to be able +to tell them apart more easily. For example, use light theme for actual DevTools +and dark theme for DevTools-on-DevTools. + +When using `--custom-devtools-frontend`, you can also right-click anywhere in +the regular DevTools and select *Inspect* from the context menu to open a +DevTools-on-DevTools window, even when the regular DevTools window is docked. + +## Using Automatic Workspace folders + +The [Workspace][workspace-documentation] feature is a powerful tool for working +on DevTools, as it allows you preview changes to styles instantly, even while +editing in your IDE (e.g. VS Code or Cider-G). With M-135, a new feature called +[Automatic Workspace folders][automatic-workspace-folders-documentation] was +introduced, which can be used to make debugging and developing DevTools easier. + +As of 2025-03-16, the feature is enabled by default in M-136 and later version. +Follow the steps [here](../ecosystem/automatic_workspace_folders.md#setup) to +set up your Chrome or Chromium instance for earlier versions of M-136 and M-135. + +Then in your `devtools-frontend` checkout, use + +``` +./third_party/chrome/chrome-linux/chrome \ + --disable-infobars \ + --custom-devtools-frontend=file://$(realpath out/Default/gen/front_end) +``` + +on Linux or + +``` +./third_party/chrome/chrome-mac/Google\ Chrome\ for\ Testing.app/Contents/MacOS/Google\ Chrome\ for\ Testing \ + --disable-infobars \ + --disable-features=MediaRouter \ + --custom-devtools-frontend=file://$(realpath out/Default/gen/front_end) \ + --use-mock-keychain +``` + +on macOS to start. The first time you do this, you'll need to connect the folder +to your workspace. + +![](./images/devtools_on_devtools_automatic.png) + +Afterwards you can immediately access the DevTools source code from within your +DevTools-on-DevTools, and for example work on CSS changes in real time, without +having to worry about extracting them out of DevTools-on-DevTools later. This +even works from within your IDE or editor: As long as the (automatic) workspace +folder is connected and DevTools-on-DevTools is open, it'll listen for changes +to these files on disk, and automatically pick up any CSS changes and apply +them. + +[self-link]: http://goo.gle/devtools-on-devtools +[workspace-documentation]: https://developer.chrome.com/docs/devtools/workspaces +[automatic-workspace-folders-documentation]: http://goo.gle/devtools-automatic-workspace-folders diff --git a/docs/cookbook/images/devtools_on_devtools_automatic.png b/docs/cookbook/images/devtools_on_devtools_automatic.png new file mode 100644 index 000000000000..3e17d293922e Binary files /dev/null and b/docs/cookbook/images/devtools_on_devtools_automatic.png differ diff --git a/docs/cookbook/images/devtools_on_devtools_starter.png b/docs/cookbook/images/devtools_on_devtools_starter.png new file mode 100644 index 000000000000..df31ec32c381 Binary files /dev/null and b/docs/cookbook/images/devtools_on_devtools_starter.png differ diff --git a/docs/cookbook/localization.md b/docs/cookbook/localization.md new file mode 100644 index 000000000000..d4c1e26aeb9d --- /dev/null +++ b/docs/cookbook/localization.md @@ -0,0 +1,320 @@ +# Localization + +## How to add a localizable string + +When you introduce a new UI string or modify an existing one that will be +displayed to the users, or remove a string that is localized, follow these steps +so that it can be localized. + +[TOC] + +### Adding a string + +Before proceeding, make sure you know the different +[localization APIs](#what-are-the-l10n-apis) and know which one you should use. + +Code example: + +```js +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 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 + */ + addAnotherString: 'Another new string I want to add, with {PH1}', +}; +const str_ = i18n.i18n.registerUIStrings('example.js', UIStrings); +const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_); + +// .... + +// in example.js file, where you want to call the string + +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 +``` + +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_);` + +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` + 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` + +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'` + 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}` + 3. If your string contains leading or trailing white space, 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 + doesn't contain leading or trailing white space anymore if you can. + 4. Backticks are only used for the text that should not be + localized. They cannot be escaped as part of the string. Check if there + are something should not be localized (see + [locked terms](#phrases-that-are-fully-locked) for more details). + + ❌ Not localized + + - 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. + +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 + +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 '{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. + +### Modifying a string + +1. Update the string you want to modify in `UIStrings` +2. Update the description and placeholders of the string if necessary + +### Removing a string + +1. Remove your string and the metadata from `UIStrings` + +## What are the l10n APIs? + +Access localized strings in the DevTools frontend using the following +localization calls. + +### i18nString + +The basic API to make a string (with or without placeholder) localizable. The +first argument is the string reference in `UIStrings` The second argument is an +object for placeholders (if any) + +```js +// at the top of example.js file, after import statements + +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 + */ + addAnotherString: 'Another new string I want to add, with {PH1} and {PH2}', +}; + +message = i18nString(UIStrings.addAnotherString, {PH1: 'a placeholder', PH2: 'another placeholder'}); +``` + +### i18nLazyString + +The `i18nString` function returns the translated string, with placeholders +resolved. To do this, it needs access to the translated strings for the user's +locale, which are not available until after DevTools has finished starting up. + +Calls to `i18nString` in the module scope will therefore fail when the module is +imported. + +```js +// Fails because i18nString runs at module-import time. +Common.Settings.registerSettingExtension({ + category: Common.Settings.SettingCategory.CONSOLE, + title: i18nString(UIStrings.groupSimilarMessagesInConsole), +... + +function notTopLevel() { + console.log(extension.title); +} +``` + +`i18nLazyString` fixes this problem by providing the same API, but returning a +closure that returns a `LocalizedString`. It can be used in top-level calls; +just make sure use-sites know it's a function now. + +```js +// Works because i18nLazyString defers the loading of the translated string until later. +Common.Settings.registerSettingExtension({ + category: Common.Settings.SettingCategory.CONSOLE, + title: i18nLazyString(UIStrings.groupSimilarMessagesInConsole), +... + +// Note we need to call title() now. +function notTopLevel() { + console.log(extension.title()); +} +``` + +### i18n.i18n.getFormatLocalizedString + +This call returns a **span element**, not a string. It is used when you want to +construct a DOM element with a localizable string, or localizable content that +contains some other DOM element. + +```js +// Create the string in UIString +/** +*@description Message in Coverage View of the Coverage tab +*@example {reload button icon} PH1 +*@example {record button icon} PH2 +*/ +clickTheRecordButtonSToStart: 'Click the reload button {PH1} to reload or record button {PH2} start capturing coverage.', + +// Element with localizable content containing two DOM elements that are buttons +const reloadButton = UI.createInlineButton(UI.Toolbar.createActionButton('coverage.start-with-reload')); +const recordButton = UI.createInlineButton(UI.Toolbar.createActionButton(this._toggleRecordAction)); +message = i18n.i18n.getFormatLocalizedString(str_, UIStrings.clickTheReloadButtonSToReloadAnd, {PH1: reloadButton, PH2:recordButton }); +``` + +### i18n.i18n.lockedString + +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 +someFunctionRequiringALocalizedString(i18n.i18n.lockedString('HTTP')); +``` + +## How to write good descriptions + +Good descriptions can improve localizability by providing more context to the +translators. There are some details that are very important to have in other +languages! + +**Good description**: + +```js +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.', +}; +``` + +**Bad description**: + +```js +const UIStrings = { + /** + * @description Elements pane 'Focusable' tooltip. + */ + computedPropertyTooltip: 'If true, this element can receive focus.', +}; +``` + +### 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. + +## 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 +// in example.js file + +import * as i18n from '../i18n/i18n.js'; +const UIStrings = { + /** + * @description Example description. Note: "robots.txt" is a canonical filename and should not be translated. + */ + requestMessage: 'Requesting for `robots.txt` ...', +}; +const str_ = i18n.i18n.registerUIStrings('example.js', UIStrings); + +const message = i18nString(UIStrings.requestMessage); +``` + +The string will rendered with robots.txt not translated and without the +backticks around it `js 'Requesting for robots.txt ...'` + +### Phrases that are fully locked + +Any text that is fully locked should not go into the UIStrings object. To make +your intention clear or to make TypeScript happy, there are two methods +`i18n.i18n.lockedString` and `i18n.i18n.lockedLazyString` that can be used +instead of having fully locked phrases via `i18nString`. + +### What should not be localized? + +In general, branding related terms and code snippets are the ones to look for, +and Sometimes some technical terms. Some examples: + +**Brandings:** Lighthouse, GitHub, DevTools, Chrome Data Saver, Safari, +BlackBerry Z30, Kindle Fire HDX, Pixel 2, Microsoft Lumia 550 + +**Code snippets:** localhost:9229, console.clear(), --memlog=all, url:a.com + +**Technical terms:** DOM, DIV, aria... diff --git a/docs/cookbook/navbar.md b/docs/cookbook/navbar.md new file mode 100644 index 000000000000..410901d2a4c5 --- /dev/null +++ b/docs/cookbook/navbar.md @@ -0,0 +1,8 @@ +# Chromium DevTools Cookbook + +[logo]: https://github.com/ChromeDevTools/devtools-logo/raw/master/logos/png/devtools-circle-48.png +[home]: README.md +[devtools]: ../README.md + +* [Chromium DevTools Cookbook][home] +* [Chromium DevTools Documentation][devtools] diff --git a/docs/cookbook/release_management.md b/docs/cookbook/release_management.md new file mode 100644 index 000000000000..554a6d25f9d3 --- /dev/null +++ b/docs/cookbook/release_management.md @@ -0,0 +1,60 @@ +# Release Management + +## Merges and Cherry-Picks + +The documentation on cherry-picks and merges (including backmerges and +backports) can be found in the +[Chromium DevTools Contribution Guidelines](../contributing/changes.md#Merges-and-cherry-picks). + +## Versioning + +There is no explicit versioning being done. At the time of writing no compelling +use case was found that would require version numbers. Commits are identified by +their commit hash, which should suffice for the projected future. + +## What happens when Chromium cuts a new Canary branch + +For each Chromium release branch, we create a mirror branch with the same name +on our repo. Rough outline: + +1. Chromium cuts a branch e.g. 3879 +1. Bots create Chromium/3879 branch on the DevTools frontend repo +1. The end + +## Handling of Beta/Stable branches + +Generally speaking, beta/stable branches are the same as Canary branches. There +is a special waterfall though, that runs tests on the beta/stable branches. + +When Chromium updates to a new major version we need to update the branch number +in +[infra/config](https://chromium.googlesource.com/devtools/devtools-frontend/+/refs/heads/infra/config) +branch of devtools-frontend. Specifically, in file buckets/ci.start, promote the +existing beta branch to stable section and modify beta section with the +corresponding branch number for the new Chromium milestone. + +```python +generate_ci_configs( + configurations = [ + ... + config_section( + name="beta", + branch='refs/heads/chromium/4044', + ), + config_section( + name="stable", + branch='refs/heads/chromium/3987', + ), + ... +``` + +After editing the above mentioned file run `lucicfg generate main.star` to have +the change propagated to the cfg files. Example: +[CL](https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/2104476) + +## Rolling/Integrating into Chromium + +The +[Skia autoroller](https://skia.googlesource.com/buildbot/+/main/autoroll/README.md) +is used. The DevTools-Frontend auto-roller state can be seen and controlled +[here](https://autoroll.skia.org/r/devtools-frontend-chromium?tab=status). diff --git a/docs/cookbook/uma_metrics.md b/docs/cookbook/uma_metrics.md new file mode 100644 index 000000000000..b58487f61674 --- /dev/null +++ b/docs/cookbook/uma_metrics.md @@ -0,0 +1,123 @@ +# UMA metrics in DevTools frontend + +[TOC] + +It is highly recommended to use +[Visual Logging](../../front_end/ui/visual_logging/README.md) for anything +related to the DevTools front-end, and use use counters or UMA histograms for +anything related to the DevTools back-end (Chromium, Blink, and V8). In some +rare cases that require complex analysis of behavior that is not reflected in +the UI you might need to also use UMA histograms in the DevTools front-end. + +(Googlers only) Generally, the histogram or action data is available in the +Timeline category of the [UMA](http://uma/) page. + +* Select the channel you want to dive into. +* Select the platforms you are interested in (for us, it is Linux, MacOS, + Windows, ChromeOS and Lacros) +* Add the metric you want to see, for example the generic histogram for action + tracking, `DevTools.ActionTaken`. + +## General histograms + +* `DevTools.ActionTaken` is a generic histogram for tracking actions performed + via the DevTools front-end. +* `DevTools.PanelShown` counts how often a given panel or tab is shown in the + DevTools front-end. + +## Histograms for the Workspaces feature + +* `DevTools.ActionTaken` records `AddFileSystemToWorkspace` (*Add Filesystem + to Workspace*), `RemoveFileSystemFromWorkspace` (*Remove Filesystem from + Workspace*) and `FileSystemSourceSelected` (*Filesystem source selected*) + according to developer interactions with the *Filesystem* tab in the + *Sources* panels sidebar. +* `DevTools.Workspaces.PopulateWallClockTime` records the wall clock time in + milliseconds elapsed while populating a project folder in the workspace. +* `DevTools.SidebarPaneShown` records the `navigator-files` (*Sources - + Filesystem*) enum whenever the *Filesystem* tab is revealed in the *Sources* + panels sidebar. + +## How to add UMA metrics in DevTools frontend + +Decide on the metric (an +[enumerated histogram](https://chromium.googlesource.com/chromium/src/tools/+/HEAD/metrics/histograms/README.md#enum-histograms) +or an +[action](https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/core/host/UserMetrics.ts;l=380) +to be logged to generic `DevTools.ActionTaken` histogram) + +1. For enumerated histogram (We use this when there are multiple related states + that should be analyzed jointly. For example, we might want to know the + source of an action like where it is performed from) + 1. Choose a name for the new histogram prefixed with `DevTools`, for + example, `DevTools.ColorPickerOpenedFrom`. + 2. Decide on the values for the different enums you want to log, for + example, `StylesPane` and `SourcesPanel` for + `DevTools.ColorPickerOpenedFrom` histogram. +2. For actions + 1. Decide on the name of the action, for example, `DeviceModeEnabled`. + +### Tracking an enumerated histogram + +1. Implement metric collection in devtools-frontend and create a CL. (Example + [CL](https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/3998783)) + 1. Add the new histogram name to the + [EnumeratedHistogram](https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/core/host/InspectorFrontendHostAPI.ts;l=351?q=InspectorFrontendHostAPI.ts) + enum. + 2. Add the same histogram name to the EnumeratedHistogram object in + [devtools_compatibility.js](https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/devtools_compatibility.js;l=396?q=devtools_compatibil) + file. + 3. Create a new function in + [UserMetrics.ts](https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/core/host/UserMetrics.ts;l=351) + with an enum parameter that corresponds to the possible values like + colorPickerOpenedFrom(type: ColorPickerOpenedFrom): void + that calls + InspectorFrontendHostInstance.recordEnumeratedHistogram. + 4. Call the new function from Host.userMetrics in the places + that you want to log the event. + 5. Create the CL. +2. Update + [histograms.xml](https://source.corp.google.com/h/chromium/chromium/src/+/main:tools/metrics/histograms/metadata/dev/histograms.xml) + and + [enums.xml](https://source.chromium.org/chromium/chromium/src/+/main:tools/metrics/histograms/enums.xml;l=26267?q=tools%2Fmetrics%2Fhistograms%2Fenums.xml) + in the Chromium codebase. + 1. Add a new enum in + [enums.xml](https://source.chromium.org/chromium/chromium/src/+/main:tools/metrics/histograms/enums.xml;l=26267?q=tools%2Fmetrics%2Fhistograms%2Fenums.xml) + with values corresponding to the values in the frontend with name + DevTools<HISTOGRAM_NAME> and make sure that enum values + 1-1 map to the values you’ve defined in the frontend. + 2. Add the new histogram definition in + [histograms.xml](https://source.corp.google.com/h/chromium/chromium/src/+/main:tools/metrics/histograms/metadata/dev/histograms.xml) + and set enum name to be the enum you've defined in the 1st step. Make + sure that histogram name is the same with the name you've used in the + frontend change. + 3. Create the CL. + +### Tracking an action + +1. Implement metric collection in devtools-frontend and create a CL. (Example + [CL](https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/3998783)) + 1. Add the action you want to track to the + [Action](https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/core/host/UserMetrics.ts;l=379) + enum in UserMetrics.ts. + 2. Call Host.userMetrics.actionTaken(Action.YOUR_ACTION) in + the places you want to the event. + 3. Create the CL. +2. Update enums in the Chromium side in + [tools/metrics/histograms/metadata/dev/enums.xml](https://source.chromium.org/chromium/chromium/src/+/main:tools/metrics/histograms/metadata/dev/enums.xml). + 1. Add the new action to the DevToolsAction enum. + 2. Create the CL. + 3. (Note: this is an optional step and does not have to be done in sync with the frontend CL). If you do not update `enums.xml` then the ID of the action will appear in dashboards rather than a readable string. + + +### Metrics Dashboard + +After the both CLs are landed we expect your histogram or action data to be +available in [UMA](http://uma/p/chrome/timeline_v2). For seeing them: + +* Select the channel you want to dive into. +* Select the platforms you are interested in (for us, it is Linux, MacOS, + Windows, ChromeOS and Lacros) +* Add the metric you want to see: either the histogram name you’ve newly added + `DevTools.ColorPickerOpenedFrom` or the generic histogram for action + tracking, `DevTools.ActionTaken`. diff --git a/docs/dependencies.md b/docs/dependencies.md index 823d328eb1e1..8e6776d11305 100644 --- a/docs/dependencies.md +++ b/docs/dependencies.md @@ -1,100 +1 @@ -# Dependencies - -[TOC] - -## Managing dependencies - -If you need to manually roll a git dependency, it's not sufficient to update the revision in the DEPS file. Instead, use -the gclient tool: -```bash -gclient setdep -r DEP@REV # for example build@afe0125ef9e10b400d9ec145aa18fca932369346 -``` -This will simultaneously update both the DEPS entry as well as the gitlink entry for the corresponding git submodule. - -To sync dependencies from Chromium to DevTools frontend, use `scripts/deps/roll_deps.py`. -Note that this may: -- Introduce unneeded whitespace/formatting changes. Presubmit scripts (e.g. invoked via `git cl upload`) will automatically fix these locally, so just apply the changes directly to your change (e.g. with `git commit --amend`) afterwards. -- Introduce breaking changes to the devtools protocol, causing compilation failures. Unfortunately these need to be handled manually as there are some changes (e.g. removing an enum value) that cannot fail gracefully. - - -The following scripts run as AutoRollers, but can be manually invoked if desired: - -- To roll the `HEAD` commit of DevTools frontend into Chromium, use `scripts/deps/roll_to_chromium.py`. -- To update DevTools frontend's DEPS, use `roll-dep`. - -## Third-party Guidelines - -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 `package.json` 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. - -[npm]: https://www.npmjs.com/ -[Chromium third-party guidelines]: https://chromium.googlesource.com/chromium/src/+/HEAD/docs/adding_to_third_party.md -[GN]: https://gn.googlesource.com/gn/+/master/docs/reference.md -[clang-format]: https://clang.llvm.org/docs/ClangFormat.html +This file has moved [here](./cookbook/dependencies.md). diff --git a/docs/design_guidelines.md b/docs/design_guidelines.md index 7617ec6a831e..e05e8dffedea 100644 --- a/docs/design_guidelines.md +++ b/docs/design_guidelines.md @@ -1,108 +1 @@ -# Chrome DevTools Design Review Guidelines - -When contributing to Chrome DevTools, please follow the process explained in this document. This is to reach a clear agreement on proposals, while involving all relevant stakeholders and decision makers. - -This process puts the IC in charge, but also requires Chrome DevTools' leaders to help the IC navigate the decision process. It includes an escalation path in case of disagreement. The overhead of this process should be proportionate to the scope of the proposal. - -**Important:** - -1. Assume good intentions. -1. Be kind and civilized. -1. Be pragmatic. - -![DevTools Design Process](design_guidelines.png) - -## Roles - -### Individual Contributor (IC) - -_LGTM_: N/A - -This person is the creator of the feature and the creator of the design documentation. - -### Technical Lead (TL) - -_LGTM_: Required. May delegate. - -The Chrome DevTools TL is Danil Somsikov (dsv@chromium.org). The TL ensures architectural consistency and good coverage by the right set of LGTM providers, and is required to sign off on the design. They may however explicitly delegate to other LGTM providers. - -In the absence of the TL, an EnReOw can act in their stead. - -### LGTM provider - -_LGTM_: Required. May delegate. - -This is a person that is required to give LGTM. These are usually ICs with significant knowledge about the areas in question. - -### Reviewer - -_LGTM_: Not required. - -This is somebody who reviews and comments on the proposal. Their input should be considered, although their LGTM is not required. - -### The Eng Review Owners (EnReOw) - -_LGTM_: Not required. However, LGTM or non-LGTM is binding. - -Stuck proposals can be escalated to the [ENG_REVIEW_OWNERS](https://cs.chromium.org/chromium/src/third_party/devtools-frontend/src/config/owner/ENG_REVIEW_OWNERS). Potential use cases of such an escalation: - -- An LGTM provider is non-responsive. -- No consensus on the design can be reached. - -The EnReOw can overrule non-LGTMs or LGTMs. - -## Detailed workflow - -1. IC shares the document with LGTM providers and reviewers according to the roles listed above. -1. LGTM providers may add more LGTM providers to remove themselves as LGTM providers. -1. LGTM providers and reviewers review the design document and add feedback. -1. IC incorporates feedback and iterates on their design document. -1. Optional: the design doc is shared publicly with devtools-dev+design@chromium.org (make sure to give comment access to contributors@chromium.org, but untick the "Notify" checkbox). -1. IC collects LGTMs by addressing feedback. Iterate if necessary. -1. Once all required LGTMs have been collected, proceed with implementation. -1. On disagreement that cannot be resolved or unreasonable delays, escalate to EnReOw. -1. Implement and iterate on CLs with code owners. We expect the implementation to take place on the public repository's main branch. Note that a series of small incremental changes has a higher chance of receiving timely reviews and actionable feedback. - -## FAQ - -### Is it worth creating a design document? - -It is always useful to have a design document. Its length can vary depending on the scope of the proposed change. - -### When should the design process be kicked off? - -As soon as possible so that a wide range of opinions can be taken into consideration. If you share your idea or prototype at a later stage, you risk having to redo the work because you missed a constraint. - -### How to decide who to add to the list of LGTM providers? - -Some pointers when people should be added to the list of LGTM providers: - -- OWNERs of the source files/directories you anticipate to touch -- Main component expert of the components you anticipate to touch -- Downstream consumers of your changes e.g. when you change an API - -### Where can I find a template for design documents? - -[Here](https://goo.gle/devtools-design-doc-template). - -### What if I made big changes to the design document? - -Make sure you still have the LGTMs e.g. by pinging the LGTM providers. - -### LGTM providers do not comment on my design document, what should I do? - -In this case you can follow this path of escalation: - -1. Ping them directly via mail, chat or comment/assignment in the doc and specifically ask them explicitly to add an LGTM or non-LGTM. -1. Get your TL involved and ask them for help. -1. Escalate to EnReOw. - -### Somebody added me as an LGTM provider to a doc, what should I do? - -Review the design document. If you think there are other people who should take a look, add them as LGTM providers or as reviewers. If you don't think you are the right person, remove yourself as LGTM provider. - -If you agree with the design, add an LGTM to the table. If you have blocking concerns, add "Not LGTM, because " to the table. Be prepared to re-review the design after another iteration. - -### How does this work together with the Blink Intents process? - -The Chromium DevTools Design Review Guidelines complement [Chromium’s feature launch process](https://www.chromium.org/blink/launching-features). If you are launching a new Web platform feature, please follow the Chromium launch process. It likely makes sense to have all the LGTMs gathered at the point in time you would send an Intent to Implement. +This document has moved [here](./contributing/design.md#Review-Guidelines). diff --git a/docs/design_guidelines.png b/docs/design_guidelines.png deleted file mode 100644 index 366ec050e59f..000000000000 Binary files a/docs/design_guidelines.png and /dev/null differ diff --git a/docs/ecosystem/README.md b/docs/ecosystem/README.md new file mode 100644 index 000000000000..798fafa9c6c8 --- /dev/null +++ b/docs/ecosystem/README.md @@ -0,0 +1,6 @@ +# Chromium DevTools Ecosystem Guide + +This guide contains information for ecosystem tools and partners regarding +integration and extension points in Chromium DevTools. + +* [Automatic Workspace Folders](automatic_workspace_folders.md) diff --git a/docs/ecosystem/automatic_workspace_folders.md b/docs/ecosystem/automatic_workspace_folders.md new file mode 100644 index 000000000000..9b5c555b84f2 --- /dev/null +++ b/docs/ecosystem/automatic_workspace_folders.md @@ -0,0 +1,107 @@ +# Automatic Workspace Folders + +[goo.gle/devtools-automatic-workspace-folders][self-link] + +We recently added a new feature to Chromium (available with M-135 and later), +which improves the ergonomics and discoverability of the +[Workspace][workspace-doc] feature, +and it's called "Automatic Workspace Folders". + +**Googlers-only:** Check out the internal resources at + +- [go/chrome-devtools:automatic-workspace-folders-design][design-doc], and +- [go/chrome-devtools:automatic-workspace-folders-demo][demo]. + +## Background + +The [Workspace][workspace-doc] feature, which was originally (re)launched as +[Workspaces 2.0][workspace-announcement] in M-63 and announced at CDS 2016, +allows developers to edit and save files in your project, effectively persisting +changes that you make in DevTools (during debugging) to your source files +directly. However, as outlined in the documentation this requires quite a bit of +[manual setup](https://developer.chrome.com/docs/devtools/workspaces#devtools), +which is + +1. not particularly obvious and discoverable, and +2. not very ergonomic when working on different projects. + +Specifically the second point is problematic, as you have to manually maintain +the list of folders in your workspace, meaning that whenever you work on a new +project (or just a separate checkout of an existing project) you'd need to add +the relevant folder manually via the Workspace tab, and when you're done with a +project (at least for a while) you'd need to remove it explicitly from the list +(otherwise the list will soon grow very long). + +## Solution + +With M-135 we've added a feature called "Automatic Workspace Folders", where +devservers can inform the developer tools running in the browser about the +project folders that they are serving, and DevTools can automatically pick that +up and connect to these folders during local debugging, and automatically +disconnect these folders when the developer navigates somewhere else. + +This information is communicated via a special JSON file that DevTools requests +from a well-known location on the devserver, as outlined in the +[DevTools Project Settings (devtools.json)][design-doc-json]. The file is named +`com.chrome.devtools.json` (for now) and located in the +`/.well-known/appspecific/` folder of the inspected page. For the automatic +workspace folders, it has to contain a `workspace` object with two properties: + +- `workspace.root` is the absolute path to the project folder (where the + source code is located). +- `workspace.uuid` is a valid UUID, ideally a v4 UUID, generated randomly when + setting up the project folder. + +An example `com.chrome.devtools.json` would look like this: + +``` +{ + "workspace": { + "root": "/Users/foobar/Projects/my-awesome-web-project", + "uuid": "53b029bb-c989-4dca-969b-835fecec3717" + } +} +``` + +Chromium DevTools will only attempt to load the `com.chrome.devtools.json` when +the origin of the inspected page is `localhost`. + +## Setup + +In M-136, which is in Canary channel at the time of this writing, the relevant +flags have been enabled by default (as of 2025-03-16). In earlier versions of +M-136 and in M-135, this feature is disabled by default. To use it, you need to +turn on two feature flags in `about:flags`: + +- [chrome://flags#devtools-project-settings](chrome://flags#devtools-project-settings) +- [chrome://flags#devtools-automatic-workspace-folders](chrome://flags#devtools-automatic-workspace-folders) + +![](./images/automatic_workspace_folders_flags.png) + +Instead of enabling the feature via `about:flags`, you can instead also enable +them from the command line: + +``` +google-chrome-canary --enable-features=DevToolsWellKnown,DevToolsAutomaticFileSystems +``` + +## Usage + +To check if your setup is correct, you can try out Benedikt’s +[Hello World][hello-world] demo project. Just follow the steps outlined in the +`README.md` there. + +## Vite + +There's also a proof-of-concept plugin for [vite](http://vite.dev) available at +[ChromeDevTools/vite-plugin-devtools-json][vite-plugin], which you can easily +add to your existing project. + +[self-link]: http://goo.gle/devtools-automatic-workspace-folders +[design-doc]: http://go/chrome-devtools:automatic-workspace-folders-design +[demo]: http://go/chrome-devtools:automatic-workspace-folders-demo +[workspace-doc]: https://developer.chrome.com/docs/devtools/workspaces +[workspaces-announcement]: https://developer.chrome.com/blog/new-in-devtools-63#workspaces +[design-doc-json]: https://goo.gle/devtools-json-design +[hello-world]: https://github.com/bmeurer/automatic-workspace-folders-hello-world +[vite-plugin]: https://github.com/ChromeDevTools/vite-plugin-devtools-json diff --git a/docs/ecosystem/images/automatic_workspace_folders_flags.png b/docs/ecosystem/images/automatic_workspace_folders_flags.png new file mode 100644 index 000000000000..865d5004fdc6 Binary files /dev/null and b/docs/ecosystem/images/automatic_workspace_folders_flags.png differ diff --git a/docs/ecosystem/navbar.md b/docs/ecosystem/navbar.md new file mode 100644 index 000000000000..fc6c05f49890 --- /dev/null +++ b/docs/ecosystem/navbar.md @@ -0,0 +1,8 @@ +# Chromium DevTools Ecosystem Guide + +[logo]: https://github.com/ChromeDevTools/devtools-logo/raw/master/logos/png/devtools-circle-48.png +[home]: README.md +[devtools]: ../README.md + +* [Chromium DevTools Ecosystem Guide][home] +* [Chromium DevTools Documentation][devtools] diff --git a/docs/get_the_code.md b/docs/get_the_code.md index 015990cbaa68..e4048aa23291 100644 --- a/docs/get_the_code.md +++ b/docs/get_the_code.md @@ -27,38 +27,79 @@ To build, follow these steps: ```bash cd devtools-frontend gclient sync -gn gen out/Default -autoninja -C out/Default +npm run build ``` The resulting build artifacts can be found in `out/Default/gen/front_end`. -There are two tips to have a faster development workflow: -* Disabling type checking for TypeScript. -* Using watch script for faster incremental builds with CSS hot reload. +The build tools generally assume `Default` as the target (and `out/Default` as the +build directory). You can pass `-t ` (or `--target=`) to use a different +target. For example + +```bash +npm run build -- -t Debug +``` + +will build in `out/Debug` instead of `out/Default`. If the directory doesn't exist, +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 + +```bash +gn gen out/Default --args="devtools_skip_typecheck=true" +``` + +or if you don't want to change the default target, use something like -#### Disabling type checking -You can disable type checking for TypeScript by using `devtools_skip_typecheck` argument: ```bash gn gen out/fast-build --args="devtools_skip_typecheck=true" ``` -#### Faster incremental builds & CSS hot reload -In addition to that, you can enable CSS hot reload while using `watch` script with `devtools_css_hot_reload_enabled` argument: +and use `npm run build -- -t fast-build` to build this target. + +### Rebuilding automatically + +You can use + ```bash -gn gen out/fast-build --args="devtools_css_hot_reload_enabled=true" +npm run build -- --watch ``` -with this and `devtools_skip_typecheck=true` in place, you can use `watch` script by: +to have the build script watch for changes in source files and automatically trigger +rebuilds as necessary. + +#### Linux system limits + +The watch mode uses `inotify` by default on Linux to monitor directories for changes. +It's fairly common to encounter a system limit on the number of files you can monitor. +For example, Ubuntu Lucid's (64bit) inotify limit is set to 8192. + +You can get your current inotify file watch limit by executing: + +```bash +cat /proc/sys/fs/inotify/max_user_watches +``` + +When this limit is not enough to monitor all files inside a directory, the limit must +be increased for the watch mode to work properly. You can set a new limit temporary with: + +```bash +sudo sysctl fs.inotify.max_user_watches=524288 +sudo sysctl -p +``` + +If you like to make your limit permanent, use: + ```bash -npm run watch -- --target=fast-build +echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf +sudo sysctl -p ``` -which will automatically apply CSS changes & instantly build changed TS files. -> Caution! `watch` script is not based on `ninja` thus the build output and behavior -> might differ with the official ninja build. In addition to that, -> there might be some cases that `watch` build doesn't reliably handle, so you -> might need to run `autoninja` and restart the script from time to time. +You may also need to pay attention to the values of `max_queued_events` and `max_user_instances` +if you encounter any errors. ### Update to latest @@ -74,6 +115,7 @@ gclient sync The revisions of git dependencies must always be in sync between the entry in DEPS and the git submodule. PRESUBMIT will reject CLs that try to submit changes to one but not the other. It can happen that dependencies go out of sync for three main reasons: + 1. The developer attempted a manual roll by only updating the DEPS file (which was the process before migrating to git submodules, see [below](#Managing-dependencies)), 1. after switching branches or checking out new commit the developer didn't run `gclient sync`, or @@ -87,7 +129,68 @@ and a separate CL with a proper roll. ### Run in a pre-built Chromium -You can run a [build](#Build) of DevTools frontend in a pre-built Chromium in order to avoid the expensive Chromium build. For example, you can use the latest version of Chrome Canary, or the downloaded binary in `third_party/chrome`. +You can run a [build](#Build) of DevTools frontend in a pre-built Chrome or Chromium in order to avoid the expensive build. Options: + +- Use the downloaded Chrome for Testing binary in `third_party/chrome`. +- Use the latest Chrome Canary. This includes any DevTools features that are only available in regular Chrome builds (`is_official_build` + `is_chrome_branded`), such as GenAI-related features. + +#### Using `npm start` script (recommended) + +With Chromium 136, we added (back) a `start` script that can be used to easily launch DevTools with pre-built [Chrome +for Testing](https://developer.chrome.com/blog/chrome-for-testing) or [Chrome Canary](https://www.google.com/chrome/canary/). +It'll also take care of automatically enabling/disabling experimental features that are actively being worked on. Use + +```bash +npm start +``` + +to build DevTools front-end in `out/Default` (you can change this to `out/foo` by passing `--target=foo` if needed), +and open Chrome for Testing (in `third_party/chrome`) with the custom DevTools front-end. This will also monitor the +source files for changes while Chrome is running and automatically trigger a rebuild whenever source files change. + +By default, `npm start` will automatically open DevTools for every new tab, you can use + +```bash +npm start -- --no-open +``` + +to disable this behavior. You can also use + +```bash +npm start -- --browser=canary +``` + +to run in Chrome Canary instead of Chrome for Testing; this requires you to install Chrome Canary manually first +(Googlers can install `google-chrome-canary` on gLinux). And finally use + +```bash +npm start -- http://www.example.com +``` + +to automatically open `http://www.example.com` in the newly spawned Chrome tab. + + +##### Controlling the feature set + +By default `npm start` will enable a bunch of experimental features (related to DevTools) that are considered ready for teamfood. +To also enable experimental features that aren't yet considered sufficiently stable to enable them by default for the team, run: + +```bash +# Long version +npm start -- --unstable-features + +# Short version +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 -- --disable-features=DevToolsWellKnown --enable-features=DevToolsFreestyler:multimodal/true +``` + +which you can use to override the default feature set. #### Running from file system @@ -116,7 +219,7 @@ Note that `$(realpath out/Default/gen/front_end)` expands to the absolute path t Open DevTools via F12 or Ctrl+Shift+J on Windows/Linux or Cmd+Option+I on Mac. -If you get errors along the line of `Uncaught TypeError: Cannot read property 'setInspectedTabId'` you probably specified an incorrect path - the path has to be absolute. On Mac and Linux, the file url will start with __three__ slashes: `file:///Users/...`. +If you get errors along the line of `Uncaught TypeError: Cannot read property 'setInspectedTabId'` you probably specified an incorrect path - the path has to be absolute. On Mac and Linux, the file url will start with **three** slashes: `file:///Users/...`. **Tip**: You can inspect DevTools with DevTools by undocking DevTools and then opening a second instance of DevTools (see keyboard shortcut above). @@ -147,6 +250,7 @@ Then start Chrome, allowing for accesses from the web server: ``` Get the list of pages together with their DevTools frontend URLs: + ```bash $ curl http://localhost:9222/json -s | grep '\(url\|devtoolsFrontend\)' "devtoolsFrontendUrl": "/devtools/inspector.html?ws=localhost:9222/devtools/page/BADADD4E55BADADD4E55BADADD4E5511", diff --git a/docs/images/debugging-e2e-tests-with-vscode.png b/docs/images/debugging-e2e-tests-with-vscode.png new file mode 100644 index 000000000000..4b949ffffee0 Binary files /dev/null and b/docs/images/debugging-e2e-tests-with-vscode.png differ diff --git a/docs/images/debugging-unit-tests-with-devtools.png b/docs/images/debugging-unit-tests-with-devtools.png new file mode 100644 index 000000000000..75e54e5db718 Binary files /dev/null and b/docs/images/debugging-unit-tests-with-devtools.png differ diff --git a/docs/images/debugging-unit-tests-with-vscode.png b/docs/images/debugging-unit-tests-with-vscode.png new file mode 100644 index 000000000000..d663119adacb Binary files /dev/null and b/docs/images/debugging-unit-tests-with-vscode.png differ diff --git a/docs/l10n.md b/docs/l10n.md index 9737160745fe..fe4a29cd9e4d 100644 --- a/docs/l10n.md +++ b/docs/l10n.md @@ -1,293 +1 @@ -# Localization - -## How to add a localizable string - -When you introduce a new UI string or modify an existing one that will be displayed to the users, or remove a string that is localized, follow these steps so that it can be localized. - -**Table of Contents** -- [Adding a string](#adding-a-string) -- [Modifying a string](#modifying-a-string) -- [Removing a string](#removing-a-string) - -### Adding a string -Before proceeding, make sure you know the different [localization APIs](#what-are-the-l10n-apis) and know which one you should use. - -Code example: - ```javascript - 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 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 - */ - addAnotherString: 'Another new string I want to add, with {PH1}', - }; - const str_ = i18n.i18n.registerUIStrings('example.js', UIStrings); - const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_); - ``` - - ```javascript - // in example.js file, where you want to call the string - - 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 - ``` -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_);` - - -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` - -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' - ``` - 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} - ``` - 3. If your string contains leading or trailing white space, 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 doesn't contain leading or trailing white space anymore if you can. - 4. Backticks are only used for the text that should not be localized. They cannot be escaped as part of the string. Check if there are something should not be localized (see [locked terms](#phrases-that-are-fully-locked) for more details). - - ❌ Not localized - - - 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. -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 -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 - '{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. - -### Modifying a string -1. Update the string you want to modify in `UIStrings` -2. Update the description and placeholders of the string if necessary - -### Removing a string -1. Remove your string and the metadata from `UIStrings` - - -## What are the l10n APIs? - -Access localized strings in the DevTools frontend using the following localization calls. - -### i18nString -The basic API to make a string (with or without placeholder) localizable. -The first argument is the string reference in `UIStrings` -The second argument is an object for placeholders (if any) - -```javascript -// at the top of example.js file, after import statements - -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 - */ - addAnotherString: 'Another new string I want to add, with {PH1} and {PH2}', -}; - -message = i18nString(UIStrings.addAnotherString, {PH1: 'a placeholder', PH2: 'another placeholder'}); -``` - -### i18nLazyString -The `i18nString` function returns the translated string, with placeholders resolved. To do this, it needs access to the translated strings for the user's locale, which are not available until after DevTools has finished starting up. - -Calls to `i18nString` in the module scope will therefore fail when the module is imported. -```javascript -// Fails because i18nString runs at module-import time. -Common.Settings.registerSettingExtension({ - category: Common.Settings.SettingCategory.CONSOLE, - title: i18nString(UIStrings.groupSimilarMessagesInConsole), -... - -function notTopLevel() { - console.log(extension.title); -} -``` - -`i18nLazyString` fixes this problem by providing the same API, but returning a closure that returns a `LocalizedString`. -It can be used in top-level calls; just make sure use-sites know it's a function now. - -```javascript -// Works because i18nLazyString defers the loading of the translated string until later. -Common.Settings.registerSettingExtension({ - category: Common.Settings.SettingCategory.CONSOLE, - title: i18nLazyString(UIStrings.groupSimilarMessagesInConsole), -... - -// Note we need to call title() now. -function notTopLevel() { - console.log(extension.title()); -} -``` - -### i18n.i18n.getFormatLocalizedString -This call returns a **span element**, not a string. It is used when you want to construct a DOM element with a localizable string, or localizable content that contains some other DOM element. - -```javascript -// Create the string in UIString -/** -*@description Message in Coverage View of the Coverage tab -*@example {reload button icon} PH1 -*@example {record button icon} PH2 -*/ -clickTheRecordButtonSToStart: 'Click the reload button {PH1} to reload or record button {PH2} start capturing coverage.', - -// Element with localizable content containing two DOM elements that are buttons -const reloadButton = UI.createInlineButton(UI.Toolbar.createActionButtonForId('coverage.start-with-reload')); -const recordButton = UI.createInlineButton(UI.Toolbar.createActionButton(this._toggleRecordAction)); -message = i18n.i18n.getFormatLocalizedString(str_, UIStrings.clickTheReloadButtonSToReloadAnd, {PH1: reloadButton, PH2:recordButton }); -``` - -### i18n.i18n.lockedString -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 -someFunctionRequiringALocalizedString(i18n.i18n.lockedString('HTTP')); -``` - -## How to write good descriptions - -Good descriptions can improve localizability by providing more context to the translators. -There are some details that are very important to have in other languages! - -**Good description**: -```javascript -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.', -}; -``` -**Bad description**: -```javascript -const UIStrings = { - /** - * @description Elements pane 'Focusable' tooltip. - */ - computedPropertyTooltip: 'If true, this element can receive focus.', -}; -``` - -### 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. - - -## 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 -// in example.js file - -import * as i18n from '../i18n/i18n.js'; -const UIStrings = { - /** - * @description Example description. Note: "robots.txt" is a canonical filename and should not be translated. - */ - requestMessage: 'Requesting for `robots.txt` ...', -}; -const str_ = i18n.i18n.registerUIStrings('example.js', UIStrings); - -const message = i18nString(UIStrings.requestMessage); -``` -The string will rendered with robots.txt not translated and without the backticks around it -```javascript - 'Requesting for robots.txt ...' -``` - -### Phrases that are fully locked -Any text that is fully locked should not go into the UIStrings object. To make your intention clear -or to make TypeScript happy, there are two methods `i18n.i18n.lockedString` and `i18n.i18n.lockedLazyString` -that can be used instead of having fully locked phrases via `i18nString`. - -### What should not be localized? -In general, branding related terms and code snippets are the ones to look for, and Sometimes some technical terms. Some examples: - -**Brandings:** -Lighthouse, GitHub, DevTools, Chrome Data Saver, Safari, BlackBerry Z30, Kindle Fire HDX, Pixel 2, Microsoft Lumia 550 -**Code snippets:** -localhost:9229, console.clear(), --memlog=all, url:a.com -**Technical terms:** -DOM, DIV, aria... +This file has moved [here](./cookbook/localization.md). diff --git a/docs/material3_guidelines.md b/docs/material3_guidelines.md deleted file mode 100644 index 11488ad1014d..000000000000 --- a/docs/material3_guidelines.md +++ /dev/null @@ -1,59 +0,0 @@ -# Material 3 for DevTools - -## Colors - -### Backgrounds - -All backgrounds should be either a surface or a container -- default toolbar color: `--sys-color-cdt-base-container` -- secondary toolbar color (e.g. Sources sidebar section headers like 'Watch' or 'Breakpoints'): `--sys-color-surface2` -- default data grid row color: `--sys-color-cdt-base-container` -- alternating grid row color: `--sys-color-surface1` -- warning message: `--sys-color-surface-yellow` -- error message: `--sys-color-surface-error` -- info message: `--sys-color-cdt-base-container` -- info bar background: `--sys-color-neutral-container` - -States: - -- hovered: `--sys-color-state-hover-on-subtle` (see Troubleshooting > 1 for details) -- selected: `--sys-color-tonal-container` -- focus-visible: `--sys-color-state-focus-highlight` -- text selection over focus: `--sys-color-state-focus-select` - -### Text - -Text should generally use on-surface, on-container -- regular (old text-primary): `--sys-color-on-surface` -- fainter (old text-secondary): `--sys-color-on-surface-subtle` -- disabled (old text-disabled): `--sys-color-text-disabled` - -For warnings, errors, text on selected/focused UI elements: -- `--sys-color-on-surface-yellow` -- `--sys-color-on-surface-error` -- `--sys-color-on-tonal-container` - -### Syntax highlighting - -Syntax highlighting should use token-something colors defined [here](crsrc.org/c/third_party/devtools-frontend/src/front_end/ui/legacy/themeColors.css;l=355) - -### Icons - -Regular (dark grey) icons should also use on-something colors -- default: `--sys-color-on-surface-subtle` -- on hover: `--sys-color-on-surface` -- disabled: `--sys-color-state-disabled` - -For colored icons, please use icon application color tokens -In case you need to add a new icon application color token, reference `--sys-color-something-bright` - -### Other elements - -In case you can’t reuse a component and need to add some new UI element, please follow the [spec](https://www.figma.com/file/5xWeeSmVQTd4yW3s6aFJ1f/CDDS-UX%2FEng-Spec-(NO-LONGER-UPDATED)?node-id=35%3A2599&mode=dev) - -### Troubleshooting - -1. For hover/focus colors for elements which background color is other than `--sys-color-cdt-base-container` - or in case you need an opaque hover color use [state layer technique](https://carbon.googleplex.com/google-material-3/pages/interaction-states/state-layers). - See [example CL](crrev.com/c/5003859) - diff --git a/docs/navbar.md b/docs/navbar.md index 0c6111daabcb..66fb0e4ea64a 100644 --- a/docs/navbar.md +++ b/docs/navbar.md @@ -8,5 +8,5 @@ * [Design Documents](https://drive.google.com/drive/folders/1JbUthATfybvMQR3yAHC4J0P7n6oftYNq) * [Contact](https://www.chromium.org/teams/devtools/) * [Bugs](https://www.chromium.org/for-testers/bug-reporting-guidelines/) -* [Markdown Style Guide](/docs/styleguide/markdown/markdown.md) +* [Style Guides](/docs/styleguide/README.md) * [Search](https://source.chromium.org/chromium/devtools/devtools-frontend/+/main:docs/) diff --git a/docs/playbook.md b/docs/playbook.md new file mode 100644 index 000000000000..d90bd410eb2e --- /dev/null +++ b/docs/playbook.md @@ -0,0 +1,176 @@ +# Chromium DevTools Playbook (aka Work With Us) + +This document serves as the Chrome DevTools Playbook and thereby provides guidance on how to work with Chrome DevTools, the types of Chrome DevTools support available, how you and your team can take advantage of that support to contribute features, and how to get help when in doubt of the type of support needed or if you need more support. + +## Getting Started + +* If you are a **Googler** see [go/chrome-devtools/work-with-us](go/chrome-devtools/work-with-us) for additional information. +* If you're a **first-time contributor** and would like some guidance to begin with, please jump to the [First Time Contributor](#first-time-devtools-contributor) section at the end of this document. +* If you are only looking for **DevTools documentations**, here is the [list](#devtools-documentation). + +To help us understand your needs and collaborate effectively, please follow the steps below. + +**Answer three preliminary questions:** + +1. [What level of debuggability do you need?](#what-level-of-debuggability-do-you-need) +2. [What is the scope of your feature request?](#what-is-the-scope-of-your-feature-request) +3. [What is your preferred collaboration mode?](#what-is-your-preferred-collaboration-mode) + +Depending on your answers, you can do one of the following: + +* [Contact DevTools team](#contact-devtools) to discuss your feature request, **OR** +* Directly design your feature, write your design doc and share with DevTools team, **OR** +* Directly write your CL(s) and submit them for review. + +## Contact DevTools + +The team uses a public mailing list for technical discussions, questions, and announcements. + +* **Email address:** [devtools-dev@chromium.org](mailto:devtools-dev@chromium.org) +* **Web archives:** [devtools-dev](https://groups.google.com/a/chromium.org/g/devtools-dev) + +### Points of Contact for Specific Topics + +For certain topics, there are dedicated points of contact (PoCs) within the DevTools team, who are considered experts and have guided initiatives within these areas in the past. + +| Topic | PoC | +| ------------------------------------- | --------------- | +| Web Compass, Interop, and Baseline | pfaffe@chromium.org | +| UI Capabilities | changhaohan@chromium.org | +| Performance | paulirish@chromium.org | +| JavaScript | szuend@chromium.org | +| WebAssembly | pfaffe@chromium.org | +| Security | dsv@chromium.org | +| Network | dsv@chromium.org | +| Extensions | pfaffe@chromium.org | + + +## What level of debuggability do you need? + +A feature is debuggable in DevTools if developers can use DevTools to more easily identify and fix a bug related to this feature. In some cases, debuggability is important for a feature's adoption, especially when a feature is complex and popular. There are three levels of debuggability, as follows. + +### No Debuggability + +DevTools doesn't offer any special support for the Web Platform Feature, but using the feature doesn't break DevTools. + +### Basic Debuggability + +DevTools helps developers understand the use of a feature. + +* **Basic debuggability for CSS features:** The feature properties are displayed and, if applicable, are editable. If the feature includes cross references, references are linkified where appropriate. +* **Basic debuggability for Web APIs:** Objects can be inspected in the sources panel (scope view, editor popover, console) and function calls can be made from the console. + +### Extended Debuggability + +DevTools offers dedicated tooling for Web Platform APIs. These tools provide helpful hints, educating developers on how to use these features effectively. Extended tooling support usually follows our [standard feature development process](go/chrome-devtools/development-process). + +* **Extended debuggability for CSS:** DevTools clearly shows the user the different usage options for a feature and offers a non-text UI to configure it where possible (e.g., color picker, flexbox picker). +* **Extended debuggability for Web APIs:** DevTools offers first-party debugging support for a feature, e.g. through automatic breakpoints. + +## What is the scope of your feature request? + +Defining the scope of the feature request helps us better understand how to allocate resources, and choose the most appropriate collaboration mode. Specifically, if you need extended debuggability support, please think about the following: + +* the minimal viable product needed to ensure a smooth adoption of the feature by developers +* the v1.0 of your feature +* nice-to-haves and out-of-scope features +* the responsibility to maintain the feature + +## What is your preferred collaboration mode? + +To scale the tooling support to the number of developer products and APIs being launched throughout Chrome (in particular the various new Web Platform APIs being introduced year-by-year), the Chrome DevTools team has created a guiding framework on how priorities are supported and provided more options for supporting teams. +Each initiative is owned by the feature team. Each engagement will have a definitive level of support defined out of the following categories: + +### Self-service + +In this self-service model, feature teams are responsible for designing and implementing tooling support, using the provided [documentation](#devtools-documentation). The DevTools team will not actively follow the project but will answer questions, similar to office hours. This type of support is designed to scale the tooling support by providing guidance and resources to product and engineering teams. + +**Example:** [Web Audio extension](https://chromewebstore.google.com/detail/audion/cmhomipkklckpomafalojobppmmidlgl?pli=1) + +### Consultation + +The Chrome DevTools team will consult the feature team on the right solution, in particular on the right usage of DevTools/CDP API, and the design of runtime introspection capabilities. The UI of the solution will either be + +* Chrome Extension, +* Chrome Internals page, or +* a separate tool. + +There is no meaningful expectation to change the DevTools frontend. + +**Example:** Privacy & Security panel + +### Review + Upstream + +The feature team does the implementation of the DevTools frontend pieces and relevant backend services required for debugging. The Chrome DevTools team does the reviews and consultations required to get the CLs landed and folding nicely into our tool surfaces (e.g. does it meet the [Chromium DevTools UI feature checklist](./checklist/ui.md)?). + +**Example:** [Early Hints DevTools support](https://docs.google.com/document/d/1IAbWeu9cj37EYaIvFpWOtnPFLxorO2YVHnxxdX0EwOU) + +### 50/50 split + +The Chrome DevTools team does the implementation of the DevTools frontend pieces. The feature team does the implementation of the backend services and plumbing required for debugging to be used in the frontend, most likely the CDP methods et. al. + +**Example:** [Autofill DevTools MVP](http://go/chrome-devtools:autofill-mvp-prd) + +### Fully owned + +The Chrome DevTools team does the implementation and design of frontend and backend pieces. + +**Examples:** Core Web Vital support in Lighthouse and DevTools, [Modern CSS color features in DevTools](http://go/chrome-devtools:modern-color-prd) + +## What are the expectations regarding maintenance? + +Any new feature comes with the potential of introducing new bugs (potentially even breaking somewhat unrelated workflows unintentionally). + +For any of the collaboration modes listed above except *Fully owned*, the Chrome DevTools team expects the feature team to maintain the tooling aspects of their feature by fixing any bugs that result from the MVP / 1.0, independent of whether these are frontend or backend bugs (except in case of 50/50 split where the Chrome DevTools team will own the frontend issues), for at least a period of **3 Chrome milestones** (since the successful launch). + +Additionally the Chrome DevTools team relies on the feature team as the domain experts for any domain-specific bugs that need to be tackled (independent of whether it’s frontend or backend related). + +## DevTools Documentation + +Depending on your answers above *and/or* your current feature stage, you may need one of these documents below. + +### basic level of debuggability + self-service collaboration mode + +* [DevTools support checklist for Blink Intents](https://chromium.googlesource.com/devtools/devtools-frontend/+/main/docs/checklist/README.md) +* [DevTools support checklist for JavaScript features](https://chromium.googlesource.com/devtools/devtools-frontend/+/main/docs/checklist/javascript.md) +* [DevTools support checklist for WebAssembly features](https://chromium.googlesource.com/devtools/devtools-frontend/+/main/docs/checklist/webassembly.md) + +### Feature request initial review or consultation mode + +* [Contact us](#contact-devtools) + +### Feature design phase + +* [DevTools UI feature checklist](./checklist/ui.md) +* [UX Style Guide](./styleguide/ux/README.md) + +## Coding phase + +* [Get the Code](./get_the_code.md) +* [Contribution Guide](./contributing/README.md) +* [UX Style Guide](./styleguide/ux/README.md) +* [Testing Guide](../test/README.md) +* [Cookbook](./cookbook/README.md) +* [Visual logging in DevTools](../front_end/ui/visual_logging/README.md) +* [Style Guides](./styleguide/README.md) +* [Architecture of DevTools](architecture_of_devtools.md) +* [Chrome DevTools Protocol (CDP)](devtools-protocol.md) +* [Resource management in DevTools](resource_management.md) + +## First time DevTools contributor? + +If you haven't worked with the Chrome DevTools team before, or if you're unsure where your feature fits, please follow the steps outlined below. + +1. Ask yourself who will be using your features and what kind of tooling support they might need to ensure a smooth adoption of your feature. + Try to think in terms of tasks and challenges developers may face, not UI elements. +2. Write a short email to devtools-dev@ with your best shot at answering those questions. It doesn't have to be perfect, and it is not a questionnaire + you need to fill to satisfy some formal process. We are mostly interested in a positive end user experience and are willing to work with you together + to achieve that. +3. We will get back to you with some initial thoughts and might ask to formalize your ideas in a design document. +4. Most likely we will ask you to book an office hours with our UXD to discuss your feature’s UX, so that developers have a consistent experience on + DevTools. Complex features where developers have to be introduced to significant new capabilities may take multiple iterations. It’s important to + get this step right. +5. Depending on the details, we will probably ask you to help us get the information exposed over the + [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/). We might also ask you to write a few straightforward CLs to + implement the UI. Don't worry, we won't ask you to re-architect our code to accommodate your feature. We will also offer all the support you + need along the way. \ No newline at end of file diff --git a/docs/policy/README.md b/docs/policy/README.md new file mode 100644 index 000000000000..e42fdc643bec --- /dev/null +++ b/docs/policy/README.md @@ -0,0 +1,7 @@ +# Chromium DevTools Policies + +This folder contains the policies relevant to the development of the Chromium +DevTools. + +1. [Chromium DevTools Slow-Close Policy](./slow-close.md) +2. [DevTools Page Zoom Accessibility Policy](./gar-page-zoom-policy.md) diff --git a/docs/policy/gar-page-zoom-policy.md b/docs/policy/gar-page-zoom-policy.md new file mode 100644 index 000000000000..b3c059e61d60 --- /dev/null +++ b/docs/policy/gar-page-zoom-policy.md @@ -0,0 +1,43 @@ +# DevTools Page Zoom Accessibility Policy + +Chrome DevTools needs to fulfill the Google Accessibility Rating (GAR) criteria. + +GAR Web’s page zoom criteria state: “Confirm the application is also usable […] +with page zoom enabled by 200% at a browser resolution of 1024x768 pixels. This +width is the equivalent to resizing a browser window to 512 pixels…” + +It is unclear what exactly this means for DevTools: DevTools can be opened as +part of the main Chrome window (docked view) or as a separate standalone window +(undocked view). In both cases the overall DevTools window/panel is resizable, +and it contains sub-panels which are themselves resizable. + +Docked DevTools, with top and bottom panel, top panel split vertically:
+![Docked DevTools with multiple panels](./images/docked-devtools.webp)
+ +Undocked DevTools, zoom factor 200%, with top and bottom panel, top panel +split horizontally:
+![Undocked DevTools with multiple panels](./images/undocked-devtools.png)
+ +As can be seen in the second screenshot above, with multiple panels open at the +same time, there is not much space left for each panel. + +Because of the panels’ resizability, we need to establish minimum panel sizes +for GAR zoom testing. We have therefore agreed on the following criteria for +a11y testing of DevTools with Page Zoom: + +* DevTools should be opened in a separate window (=undocked view), with a + resolution of 1024x768 pixels and a zoom factor of 200%. +* When testing a panel in the top drawer (Elements panel, Network panel, + Performance panel,…), the whole 1024x768 pixel window should be available for + the panel. Bottom drawer panels should be closed by pressing ‘Esc’. +* When testing a panel in the bottom drawer, the panel should not be smaller + than half the size of the overall DevTools window (i.e. a height of 384 pixels + at 200% zoom). + +Undocked DevTools, 1024x768 pixels, zoom factor 200%, ready for page zoom a11y +testing of the bottom panel:
+![DevTools page zoom a11y testing](./images/devtools-gar-testing.png)
+ +## References + +[Supported viewport sizes and zoom levels in Chrome DevTools](https://goo.gle/smoldevtools) diff --git a/docs/policy/images/devtools-gar-testing.png b/docs/policy/images/devtools-gar-testing.png new file mode 100644 index 000000000000..c2e7b0ce12e8 Binary files /dev/null and b/docs/policy/images/devtools-gar-testing.png differ diff --git a/docs/policy/images/docked-devtools.webp b/docs/policy/images/docked-devtools.webp new file mode 100644 index 000000000000..7b58ddd24c79 Binary files /dev/null and b/docs/policy/images/docked-devtools.webp differ diff --git a/docs/policy/images/undocked-devtools.png b/docs/policy/images/undocked-devtools.png new file mode 100644 index 000000000000..16736b1f97bf Binary files /dev/null and b/docs/policy/images/undocked-devtools.png differ diff --git a/docs/policy/slow-close.md b/docs/policy/slow-close.md new file mode 100644 index 000000000000..5e1e10bb497d --- /dev/null +++ b/docs/policy/slow-close.md @@ -0,0 +1,52 @@ +# Chromium DevTools Slow-Close Policy + +[goo.gle/devtools-slow-close] +([go/chrome-devtools:slow-close-policy]) + +In November 2024, we instituted a slow close policy for Chrome DevTools to +automatically maintain hygiene of our bug database. We ended up with a list +of over 1650 open bugs and over 750 open feature requests, some of them going +back over 10 years, which was not only challenging to maintain, but also made +it difficult to determine what's relevant and where we should invest our +resources best. + +By automatically nudging and closing stale bugs and feature requests, we can +reduce this burden, and better communicate to our users what will actually be +actioned, and hear from them what remains relevant. + +[TOC] + +## Rules + +The criteria for slow close: + +- Status: unassigned +- Type: Bug or Feature Request +- Created: over 3 years ago +- Last updated: over 90 days ago +- Popularity: (cc count + vote count) < 10 +- No open descendants + +Googlers can mark issues as exempt from slow close by adding them to the +[`DevTools-Blintz-Close-Exempt` hotlist](https://issues.chromium.org/hotlists/6459983). + +## Process + +The automation runs on a daily basis, and performs the following steps: + +- Issues that meet the criteria outlined above are added to the + [`DevTools-Blintz-Close-Candidate` hotlist](https://issues.chromium.org/hotlists/6459982) + for closure. +- If 14 days have passed and no updates have occurred, the issue will be closed + and moved to the + [`DevTools-Blintz-Close` hotlist](https://issues.chromium.org/hotlists/6460812) + for recording purposes. +- No more than 25 issues will be updated in a single run. + +## Implementation + +**(Googlers only)**: This is implemented in [go/chrome-devtools:blintz]. + +[goo.gle/devtools-slow-close]: http://goo.gle/devtools-slow-close +[go/chrome-devtools:slow-close-policy]: http://go/chrome-devtools:slow-close-policy +[go/chrome-devtools:blintz]: http://go/chrome-devtools:blintz diff --git a/docs/release_management.md b/docs/release_management.md index 2b5e3e9255ff..4d8182e7fd17 100644 --- a/docs/release_management.md +++ b/docs/release_management.md @@ -1,53 +1 @@ -# Release Management - -## Merges and Cherry-Picks - -The documentation on cherry-picks and merges (including backmerges and backports) can be found in [`contributing_changes.md`](contributing_changes.md#merges-and-cherry_picks). - -## Versioning - -There is no explicit versioning being done. At the time of writing no compelling -use case was found that would require version numbers. Commits are identified by their commit hash, which should suffice for the projected future. - -## What happens when Chromium cuts a new Canary branch - -For each Chromium release branch, we create a mirror branch with the same name on our repo. Rough -outline: - -1. Chromium cuts a branch e.g. 3879 -1. Bots create Chromium/3879 branch on the DevTools frontend repo -1. The end - -## Handling of Beta/Stable branches - -Generally speaking, beta/stable branches are the same as Canary branches. There -is a special waterfall though, that runs tests on the beta/stable branches. - -When Chromium updates to a new major version we need to update the branch number -in [infra/config](https://chromium.googlesource.com/devtools/devtools-frontend/+/refs/heads/infra/config) -branch of devtools-frontend. Specifically, in file buckets/ci.start, promote -the existing beta branch to stable section and modify beta section with the -corresponding branch number for the new Chromium milestone. - -```python -generate_ci_configs( - configurations = [ - ... - config_section( - name="beta", - branch='refs/heads/chromium/4044', - ), - config_section( - name="stable", - branch='refs/heads/chromium/3987', - ), - ... -``` - -After editing the above mentioned file run `lucicfg generate main.star` to have the change propagated to the cfg files. -Example: [CL](https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/2104476) - -## Rolling/Integrating into Chromium - -The [Skia -autoroller](https://skia.googlesource.com/buildbot/+/main/autoroll/README.md) is used. The DevTools-Frontend auto-roller state can be seen and controlled [here](https://autoroll.skia.org/r/devtools-frontend-chromium?tab=status). +This file has moved [here](./cookbook/release_management.md). diff --git a/docs/styleguide/README.md b/docs/styleguide/README.md new file mode 100644 index 000000000000..9cf83085f483 --- /dev/null +++ b/docs/styleguide/README.md @@ -0,0 +1,8 @@ +# Chromium DevTools Style Guides + +This folder contains style guides relevant to the development of the Chromium +DevTools, specifically focused on the front-end aspects of the developer tools. + +1. [Chromium DevTools TypeScript Style Guide (goo.gle/devtools-tsstyle)](./tsstyle/README.md) +1. [Chromium DevTools UX Style Guide (goo.gle/devtools-ux-style-guide)](./ux/README.md) +1. [Markdown Style Guide in Chromium](./markdown/markdown.md) diff --git a/docs/styleguide/tsstyle/README.md b/docs/styleguide/tsstyle/README.md new file mode 100644 index 000000000000..7d89045ebfe5 --- /dev/null +++ b/docs/styleguide/tsstyle/README.md @@ -0,0 +1,58 @@ +# Chromium DevTools TypeScript Style Guide + +[goo.gle/devtools-tsstyle](http://goo.gle/devtools-tsstyle) ([go/devtools-tsstyle](http://go/devtools-tsstyle)) + +By default we assume the [Google TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html) +as the base set of style rules for our TypeScript. Some of the TypeScript style guide limits certain +features based on the Google internal toolchain, we are able to take advantage of certain features +that the Google internal TypeScript developers cannot. This document, therefore, primarily specifies +modifications to the official Google TypeScript style guide. + +## Class Members + +* Use JavaScript private fields over the TypeScript `private` visibility annotation. + This ensures that the output JavaScript more closely matches the authored TypeScript. +* Do not use `_` to prefix private fields. + * TypeScript already knows they are private, and the `#` prior to the field’s name denotes it as private. + * Note: you will not be able to mix the private visibility modifier with a private field. It will always be private. +* Do not use `_` to prefix private functions. + * As above, TypeScript already knows they are private. +* Use getters and setters where they make sense. + * We are transpiling to JavaScript where they remain intact. + +## Control flow statements & blocks + +* Do not omit curly braces for blocks of code. + +## Optimization compatibility + +We compile to ESNext in TypeScript. This means that the JavaScript we output is as close to the authored TypeScript as possible. +There is therefore no need to consider transpiling optimizations. + +* You may use `const enum` without restriction. + +## Decorators + +We do not currently support these or plan to add them at this time. + +## Imports + +* Use `import * as entrypoint from 'path/to/entrypoint/entrypoint.js'` wherever possible + * This is currently enforced by lint rules. +* Avoid export type. Always export the symbols themselves (which will include the types) +* You are free to use import type, but only do so when importing the symbol would create a circular dependency and when only the types are needed. + +## Use of `any` + +This is already in the TypeScript style guide, but to reiterate, DevTools code should not use `any` wherever possible. All current instances of any are to manage legacy code, and ideally these will be rewritten or refactored out over time. + +## Enums + +* Prefer `const enum` whenever possible. `const enum`s are only available at compile time, and at runtime their values are inlined into the code, which helps decrease our bundle size. + * This differs from the Google TypeScript Style Guide but they rely on the Closure compiler to optimise the bundle size which we do not. +* Explicitly give enum members a string value: `const enum Foo { A = 'a' }`. This keeps the values much easier to debug than trying to figure which value TypeScript assigned to any member. +* Name enum members in all capitals. + +## Other interesting notes + +1. [go/typescript-return-only-generics](http://go/typescript-return-only-generics) (Googlers only) diff --git a/docs/styleguide/ux/README.md b/docs/styleguide/ux/README.md new file mode 100644 index 000000000000..d4a62c122f68 --- /dev/null +++ b/docs/styleguide/ux/README.md @@ -0,0 +1,21 @@ +# Chromium DevTools UX Style Guide + +[goo.gle/devtools-ux-style-guide](https://goo.gle/devtools-ux-style-guide) + +These guidelines cover the best practices for extending Chromium DevTools' +user interface. + +## Table of contents + +1. [How to organize UI](organizing.md) +1. [How to style UI](styleguide.md) +1. [How to (re)use common UX patterns](patterns.md) +1. [How to write UI text](writing.md) +1. [How to format numbers](numbers.md) +1. [Glossary](glossary.md) + +## UI reviews +If you make changes to DevTools UI, make sure to involve us **early**, i.e. already in the +UI design stage. See also the [Chrome DevTools Design Review Guidelines](../../contributing/design.md#Review-Guidelines) + +Back to the [Chromium DevTools Documentation](../../README.md). diff --git a/docs/styleguide/ux/components.md b/docs/styleguide/ux/components.md new file mode 100644 index 000000000000..8959dcedc5dc --- /dev/null +++ b/docs/styleguide/ux/components.md @@ -0,0 +1,269 @@ +# Components + +[TOC] + +## Buttons + +![Button component](images/button-text-variations.png) + +### Variations + +#### Primary buttons + +![Primary button component](images/primary-buttons.png) + +Primary buttons are the most prominent type of button available. They are used +for a single, necessary action a developer must complete, or for a highly +recommended, promoted action. Use them sparingly and with purpose. + +#### Tonal buttons + +![Tonal button component](images/tonal-buttons.png) + +Use tonal buttons in dialogs for actions that stand secondary to a primary +action and are not a cancel or close action. + +#### Outlined buttons + +![Outlined button component](images/outlined-buttons.png) + +Outlined buttons are the default button style. Use them for regular actions in +the UI or to cancel dialogs. + +#### Text buttons + +![Text button component](images/text-buttons.png) + +Text buttons are the least prominent button choice. Use them in cases outlined +buttons would create too much visual noise. + +#### Micro buttons + +Micro buttons are used if we have a small line height. + +#### Icon buttons + +![Icon button variations](images/button-icon-variations.png) + +Use icon buttons in toolbars of contextual actions that shouldn’t take up much +space. + +### Usage + +#### Developer guidelines + +##### Dos and Don'ts + +###### Do + + * Use + [`devtools-button`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/ui/components/buttons/Button.ts) + for Primary, Outlined, Text, Micro and Icon buttons + * Use + [`ToolbarButton`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/ui/legacy/Toolbar.ts;drc=2017cd8a8925f180257662f78eaf9eb93e8e394d;bpv=1;bpt=1;l=555?q=toolbar.ts%20devtools&ss=chromium&gsn=ToolbarButton&gs=KYTHE%3A%2F%2Fkythe%3A%2F%2Fchromium.googlesource.com%2Fcodesearch%2Fchromium%2Fsrc%2F%2Fmain%3Flang%3Dtypescript%3Fpath%3Dfront_end%2Fui%2Flegacy%2FToolbar%23ToolbarButton%2523type) + for buttons inside + [`Toolbars`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/ui/legacy/Toolbar.ts). + Underneath they make use of `devtools-button`. + +###### Don'ts + + * Use `