diff options
Diffstat (limited to 'chromium/third_party/devtools-frontend/src/docs')
15 files changed, 773 insertions, 9 deletions
diff --git a/chromium/third_party/devtools-frontend/src/docs/design_guidelines.md b/chromium/third_party/devtools-frontend/src/docs/design_guidelines.md new file mode 100644 index 00000000000..7406978470f --- /dev/null +++ b/chromium/third_party/devtools-frontend/src/docs/design_guidelines.md @@ -0,0 +1,143 @@ +# Chrome DevTools Design Review Guidelines + +Please make sure to adhere to the following guidelines when applicable. There are multiple drivers for the formalization of the design process in Chromium DevTools: + +1. Make it clear to the Individual Contributor (IC) who the decision makers are and highlight what the path forward is in the case where a project is not proceeding due to technical disagreement. +1. Create a forum to have straight-forward design discussions. +1. Ensure that the Technical Lead (TL) and the Engineering Manager (EnReOw) are aware of all significant changes and give them a chance to comment on designs early on. +1. Increase the involvement of all contributors all over the globe. + +## Summary + +**Important:** + +1. Assume good intentions. +1. Be kind and civilized. +1. Be pragmatic. + +The proposed workflow in here is based on the following assumptions and pillars: + +1. Put the IC in charge. They are the ones who facilitate the process. +1. The technical leaders (TL, EnReOw) are tasked to help the ICs navigate the territory and find the right LGTM providers. +1. If a feature is uncontroversial, nearly no overhead should be created. +1. If there's a lot of controversy, the feature can be escalated to a dedicated design review meeting where future steps are decided. + + + +## Roles + +### Individual Contributor (IC) + +_LGTM_: N/A + +This person is the creator of the feature and the creator of the design documentation. + +### The Technical Leads (TL) + +_LGTM_: Must have + +An LGTM is needed from the DevTools TLs, which are Benedikt Meurer (bmeurer@chromium.org) and Rob Paveza (Rob.Paveza@microsoft.com) at this point, in order to ensure architectural consistency. The TLs are also responsible for finding the right LGTM providers (i.e. the domain experts) to sign off on the design. + +In the absence of the TLs, the EnReOw takes over the responsibility. + +### LGTM provider + +_LGTM_: Must have + +This is a person that is required to give LGTM. These are usually ICs which have significant knowledge about the areas in question. + +### “Random” reviewer of the document (RRotD) + +_LGTM_: Not required + +This is somebody who is simply reviewing and comment on the proposal. Their input should be considered, although their LGTM is not required. + +### The Eng Review Owners (EnReOw) + +_LGTM_: Not required + +Stuck proposals can be escalated to the [ENG_REVIEW_OWNERS](https://cs.chromium.org/chromium/src/third_party/devtools-frontend/src/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. Start: IC decides to work on a feature/gets a feature assigned to them +1. IC sends out their early design doc/explainer/one pager to a few RRotDs + - Prototypes are considered part of the "design doc" +1. IC adds people to the list of LGTM providers that the IC thinks should give their LGTM. The TL is a must have on the list of LGTM providers. +1. IC incorporates feedback. +1. TL adds more people to the list of LGTM providers. +1. IC sends out the early design doc based on the Chromium DevTools design template to devtools-dev+design@chromium.org (please make sure to give comment access to contributors@chromium.org, remembering to untick the "Notify" checkbox). +1. IC collects the LGTMs. TL helps them. +1. LGTM provider reviews document, add comments and gives either an LGTM or not LGTM at the beginning of the document. If they add a not LGTM, they are obligated to list the reason(s). +1. Optional: LGTM providers can remove themselves from the list of LGTM providers and/or suggest other LGTM providers +1. IC and TL work to resolve the unresolved issues. +1. If all LGTM are gathered send an email to devtools-dev@chromium.org (e.g. by pinging the original thread) and announce implementation. +1. Optional: If IC and TL are blocked and/or want to have a broader discussion they can escalate the issue to the EnReOw. +1. IC sends a mail to the EnReOw + 1. TL in CC + 1. Link to design doc in the mail +1. The EnReOw is obligated to review the doc and optionally add himself to the list of LGTM providers. +1. Next steps to unblock the feature are decided. +1. If the blocker is not resolved afterwards or new, unresolvable blockers are discovered, goto 8. +1. Optional: If "not LGTMs" are added after the feature was approved already, they should be treated like normal, unresolved issues. + +- IC and TL work to resolve the unresolved issues. + +1. End: IC proceeds with the feature. + +_And always remember_: + +- Assume good intentions. +- Be kind and civilized. +- Be pragmatic. + +## FAQ + +### How to decide if the feature is worthy to have a design document? + +Some pointers when a design doc is appropriate: + +- Touches at least two components +- Needs reconciliation with non-DevTools projects e.g. V8, Blink +- Take longer than 1 week of effort to implement +- It is a new web platform capability +- Platform specific code will be touched +- User facing (UX) changes or additions + When in doubt, ask the TL. + +### 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](http://bit.ly/devtools-design-doc-template). + +### What if something big changes? + +Make sure you still have the LGTMs e.g. by pinging the LGTM providers with a clear, reasonable deadline to veto. + +### LGTM providers don’t comment on my doc, 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? + +Chromium DevTools is aiming to make decisions more transparent and escalation more straight-forward. If you think the design is good enough and should be done add an “LGTM” to the table cell next to your name. +If you have blocking concerns or remarks, please add “Not LGTM, because <reason>” into the table cell next to your name. Be prepared to get asked for another round of review. + +### How does this work together with the Blink Intents process? + +The Chromium DevTools Design Review Guidelines complement [Chromiums 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/chromium/third_party/devtools-frontend/src/docs/langpacks/README.md b/chromium/third_party/devtools-frontend/src/docs/langpacks/README.md deleted file mode 100644 index 992938ac3b3..00000000000 --- a/chromium/third_party/devtools-frontend/src/docs/langpacks/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# Localization FAQs - -- [How to add a localizable string?](adding_strings.md) -- [What are the localization APIs?](localization_apis.md) -- [How to add descriptive information to GRDP messages?](grdp_files.md) -- [How to prevent specific terms being localized?](locked_terms.md)
\ No newline at end of file diff --git a/chromium/third_party/devtools-frontend/src/docs/localization/README.md b/chromium/third_party/devtools-frontend/src/docs/localization/README.md new file mode 100644 index 00000000000..2fe068cc6c5 --- /dev/null +++ b/chromium/third_party/devtools-frontend/src/docs/localization/README.md @@ -0,0 +1,16 @@ +# Localization FAQs + +DevTools Localization is in the process of moving away from the existing model (V1) to the new one (V2). See sections below for details on each model. +- [How do I know which version to use when adding a string?](check_version.md) + +## Localization V1 +- [How to add a localizable string?](adding_strings.md) +- [What are the localization APIs?](localization_apis.md) +- [How to add descriptive information to GRDP messages?](grdp_files.md) +- [How to prevent specific terms being localized?](locked_terms.md) + +## Localization V2 +- [How to add a localizable string?](adding_strings_V2.md) +- [What are the localization APIs?](localization_apis_V2.md) +- [How to write good descriptions for strings?](descriptions.md) +- [How to prevent specific terms being localized?](locked_terms_V2.md) diff --git a/chromium/third_party/devtools-frontend/src/docs/langpacks/adding_strings.md b/chromium/third_party/devtools-frontend/src/docs/localization/adding_strings.md index 4553afa2c6b..619329f42b3 100644 --- a/chromium/third_party/devtools-frontend/src/docs/langpacks/adding_strings.md +++ b/chromium/third_party/devtools-frontend/src/docs/localization/adding_strings.md @@ -128,7 +128,7 @@ Before proceeding, make sure you know the different [localization APIs](localiza ### Frontend GRDP file 1. Run any of the following commands to have new strings automatically added to the corresponding grdp file: - `git cl presubmit --upload`, or - - `node scripts/check_localizable_resources.js --autofix` under the devtools folder + - `node scripts/localization/check_localizable_resources.js --autofix` from devtools-frontend/src folder 2. Manually add information to the new grdp message. See [Adding Descriptive Information to GRDP Messages](grdp_files.md) ## Modifying a string diff --git a/chromium/third_party/devtools-frontend/src/docs/localization/adding_strings_V2.md b/chromium/third_party/devtools-frontend/src/docs/localization/adding_strings_V2.md new file mode 100644 index 00000000000..1dbd5d3aaa3 --- /dev/null +++ b/chromium/third_party/devtools-frontend/src/docs/localization/adding_strings_V2.md @@ -0,0 +1,109 @@ +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](localization_apis_V2.md) and know which one you should use. + +Code example: + ```javascript + // 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_ = Common.i18n.registerUIStrings('example.js', UIStrings); + ``` + + ```javascript + // in example.js file, where you want to call the string + + const message1 = Common.i18n.getLocalizedString(str_, UIStrings.addThisString); + console.log(message1); // The new string I want to add + + const message2 = Common.i18n.getLocalizedString(str_, 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 add the line `const str_ = Common.i18n.registerUIStrings({the current fileName.js, relative to front_end}, UIStrings);` so the new UIStrings can be registered into `en-US.json`. + + +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 <b>leading or trailing white space</b>, it's usually an indication that it's half of a sentence. This decreases localizability as it's essentially concatenating. Modify it so that it doesn't contain leading or trailing white space anymore if you can. + 4. Check if there are something should not be localized (see [locked_terms](locked_terms_V2.md)) for more details. + + ❌ + + - Numbers: 1, 1.23, 1.2e3, etc. + - Application data: error codes, enums, database names, rgba, urls, etc. + + ✔️ + + - Words and sentences + - Punctuation + - Units of measurement: kb/s, mph, etc. +4. The following commands would add the new strings to `en-US.json`: + - `git cl presubmit --upload`, or + - `node third_party/i18n/collect-strings.js` under the DevTools src folder + +## 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` diff --git a/chromium/third_party/devtools-frontend/src/docs/localization/check_version.md b/chromium/third_party/devtools-frontend/src/docs/localization/check_version.md new file mode 100644 index 00000000000..8922843d834 --- /dev/null +++ b/chromium/third_party/devtools-frontend/src/docs/localization/check_version.md @@ -0,0 +1,9 @@ +Localization V1 and V2 would both exist in the DevTools during the migration. To check whether the file you are touching is migrated or not: +1. Is there a `const UIStrings = ` declare at the top of the file after import statements? +✔️: V2 +2. Is there `i18n` referenced in the file? +✔️: V2 +3. Is there `ls`` `, `Common.UISting()`, or `UI.formatLocalized()` in the file? +✔️: V1 + +Presubmit step would also inform you if there are V1 APIs used in a migrated file. diff --git a/chromium/third_party/devtools-frontend/src/docs/localization/descriptions.md b/chromium/third_party/devtools-frontend/src/docs/localization/descriptions.md new file mode 100644 index 00000000000..a835983b2ae --- /dev/null +++ b/chromium/third_party/devtools-frontend/src/docs/localization/descriptions.md @@ -0,0 +1,28 @@ +## Description +Good descriptions can improve localizability as it will provide more context to the translators. + +**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? +- Where is the text located? (e.g. button, title, link, pull-down menu in the Sources pane) +- What triggers the string and/or what is the result? What page or text comes before and after? +- What do the placeholders stand for? Will this message replace a placeholder in another message? Do they need to be arranged in a certain way? +- Is this a verb or a noun? If it's an adjective, what does it refer to? +- Who is the message intended for (e.g. accessible label)? diff --git a/chromium/third_party/devtools-frontend/src/docs/langpacks/grdp_files.md b/chromium/third_party/devtools-frontend/src/docs/localization/grdp_files.md index 89d66ba050d..89d66ba050d 100644 --- a/chromium/third_party/devtools-frontend/src/docs/langpacks/grdp_files.md +++ b/chromium/third_party/devtools-frontend/src/docs/localization/grdp_files.md diff --git a/chromium/third_party/devtools-frontend/src/docs/langpacks/localization_apis.md b/chromium/third_party/devtools-frontend/src/docs/localization/localization_apis.md index fb579c36935..fb579c36935 100644 --- a/chromium/third_party/devtools-frontend/src/docs/langpacks/localization_apis.md +++ b/chromium/third_party/devtools-frontend/src/docs/localization/localization_apis.md diff --git a/chromium/third_party/devtools-frontend/src/docs/localization/localization_apis_V2.md b/chromium/third_party/devtools-frontend/src/docs/localization/localization_apis_V2.md new file mode 100644 index 00000000000..a0bb62876a9 --- /dev/null +++ b/chromium/third_party/devtools-frontend/src/docs/localization/localization_apis_V2.md @@ -0,0 +1,40 @@ +Localizable strings in the DevTools frontend need to be wrapped in localization calls. There are two different calls. + +## Common.i18n.getLocalizedString +The basic API to make a string (with or without placeholder) localizable. +The first argument is the UIString instance function `str_`. +The second argument is the string reference in `UIStrings` +The third 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 = Common.i18n.getLocalizedString(str_, UIStrings.addAnotherString, {PH1: 'a placeholder', PH2: 'another placeholder'}); +``` + +## Common.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 = Common.i18n.getFormatLocalizedString(str_, UIStrings.clickTheReloadButtonSToReloadAnd, {PH1: reloadButton, PH2:recordButton }); +``` diff --git a/chromium/third_party/devtools-frontend/src/docs/langpacks/locked_terms.md b/chromium/third_party/devtools-frontend/src/docs/localization/locked_terms.md index 4532dfd94a0..4532dfd94a0 100644 --- a/chromium/third_party/devtools-frontend/src/docs/langpacks/locked_terms.md +++ b/chromium/third_party/devtools-frontend/src/docs/localization/locked_terms.md diff --git a/chromium/third_party/devtools-frontend/src/docs/localization/locked_terms_V2.md b/chromium/third_party/devtools-frontend/src/docs/localization/locked_terms_V2.md new file mode 100644 index 00000000000..cba27389224 --- /dev/null +++ b/chromium/third_party/devtools-frontend/src/docs/localization/locked_terms_V2.md @@ -0,0 +1,27 @@ +## How to prevent a term being localized? +If a string contains some terms that should not be localized, convert them to placeholders +For example, if the `robots.txt` in string `Requesting for robots.txt ...` should not be translated: + +```javascript +// in example.js file +const UIStrings = { + /** + * @description Example description. Note: "robots.txt" is a canonical filename and should not be translated. + * @example {robots.txt} PH1 + */ + requestMessage: 'Requesting for {PH1} ...', +}; +const str_ = Common.i18n.registerUIStrings('example.js', UIStrings); + +const message = Common.i18n.getLocalizedString(str_, UIStrings.requestMessage, {PH1: 'robots.txt'}); +``` + +## 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/chromium/third_party/devtools-frontend/src/docs/RELEASE_MGMT.md b/chromium/third_party/devtools-frontend/src/docs/release_management.md index 2733bc9d82b..327bdeeec57 100644 --- a/chromium/third_party/devtools-frontend/src/docs/RELEASE_MGMT.md +++ b/chromium/third_party/devtools-frontend/src/docs/release_management.md @@ -1,15 +1,17 @@ # Release Management ## Merges and Cherry-Picks + The documentation on this can be found in the main [README.md](../README.md). ## 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 +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 @@ -17,6 +19,7 @@ outline: 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. @@ -48,4 +51,3 @@ Example: [CL](https://chromium-review.googlesource.com/c/devtools/devtools-front The [Skia autoroller](https://skia.googlesource.com/buildbot/+/master/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/chromium/third_party/devtools-frontend/src/docs/triage_guidelines.md b/chromium/third_party/devtools-frontend/src/docs/triage_guidelines.md new file mode 100644 index 00000000000..333cd79cda1 --- /dev/null +++ b/chromium/third_party/devtools-frontend/src/docs/triage_guidelines.md @@ -0,0 +1,120 @@ +# Triage Guidelines + +## Disclaimer + +The most important thing: please use common sense. The guidelines below are likely not exhaustive and do not cover every case. + +## What should be triaged? + +All `Untriaged` DevTools issues, as well as any `Unconfirmed` issues that also have the `TE-NeedsTriageHelp` label need to be triaged. + +[[Query]](https://bugs.chromium.org/p/chromium/issues/list?q=component%3APlatform%3EDevTools%20status%3AUntriaged%20OR%20component%3APlatform%3EDevTools%20status%3AUnconfirmed%20label%3ATE-NeedsTriageHelp) + +## Who is triaging? + +Right now there is a Google-internal rotation set-up, with people that do weekly shifts. +As Microsoft is in an opposite timezone they have a similar rotation on the same triage queue, but during a different time. + +- Google rotation: GMT+1 +- MS rotation: GMT-9 + +## What are the SLOs? + +[[Query]](https://bugs.chromium.org/p/chromium/issues/list?q=component%3APlatform%3EDevTools%20status%3AUntriaged%20modified-before%3Atoday-7%20OR%20component%3APlatform%3EDevTools%20status%3AUnconfirmed%20label%3ATE-NeedsTriageHelp%20modified-before%3Atoday-7) + +Issues in the untriaged queue should receive a meaningful response within a business week. This means that the goal is to make the query mentioned above return zero issues. + +## How are priorities defined? + +- P0: This needs to be urgently done, fire drill alert! + - Most of the time, this seldom needs to be used. + - Critical security exploits that affect stable are a good example for a P0 + - DevTools crashing on startup is a good example +- P1: This is important. Let’s aim to get this done next + - Non-critical security fixes will likely be in this category + - Regression bugs will be likely in this category + - Important features that partners are waiting for might be in this category +- P2: We want to do that. The exact time of delivery is not that important though. + - General feature work will likely be in this category + - Non-severe bugs +- P3: This is nice, but not important. We unlikely will do work here. + - Edge-case bugs might fit this category + - Non-important feature requests too + +## How should issues be triaged? + +An issue is triaged when it meets the following criteria: + +- Priority is set correctly +- Component is set correctly +- Type is set correctly especially consider Feature vs Bug vs Bug-Regression +- Status is set correctly (Available most of the time) +- Request bisection from the Chrome Test Engineer team by adding the label "Needs-Bisect". + +### Setting Assigned or Available + +Set issues to Available if they don’t need immediate action and nobody right now and in the short-term future (an iteration) needs to work on it. + +If you think they should be addressed in the short-term please add the label “Hotlist-DevTools-CurrentSprint”. + +If you think they should be addressed mid-term or the next iteration, please add the label “Hotlist-DevTools-Backlog” + +Issues that are handled by Microsoft have the label “Hotlist-DevTools-MS-Backlog” and “Hotlist-DevTools-MS-CurrentSprint” respectively and can be considered triaged. + +If you think they are super urgent, please assign them to yangguo@chromium.org and cc bmeurer@chromium.org and hablich@chromium.org. + +### Closing issues + +Don’t be afraid to close issues with WontFix if: + +- Bugs that are not reproducible +- After two weeks you did not get a response back from the reporter on a question +- The requested “bug” is the intended behavior + Make sure that you bundle the WontFix with a brief comment explaining it e.g. “Setting to WontFix because not reproducible.” + +## FAQ + +### What if the issue belongs to another team? + +If you think the to-triage issue is not a DevTools issue, please simply set it to a component that you think it should belong to and potentially remove the DevTools component. Make sure that the status is set to Untriaged. Feel free to CC people that you think might help with triaging this. +This essentially moves the issue out of the DevTools triage queue into another team’s queue. + +### What if the issue is best handled by Microsoft? + +If you think the to-triage issue or feature request is best handled by Microsoft then add the label "msft-consider" to the issue along with completing the other normal triage steps. + +### There is a feature request I am unsure how to handle. What should I do? + +Please set the request to Available and add the label “Hotlist-DevTools-ProductReview”. + +### How do I indicate that a bug should block a release? + +The combination of the label “M-<milestone>” and “Release-Block-<channel>” signals that this very bug is blocking a release. Examples: + +- M-80, Release-Block-Stable + - This blocks the release of 80 to the Stable channel + - Depends in which release channel 80 is, this might not be an urgent (but still important bug to fix) +- M-81, Release-Block-Beta + - This blocks the release of 81 to the Beta channel + - Depends in which release channel 81 is, this might not be an urgent (but still important bug to fix) +- M-81, Release-Block-Dev + - This blocks the release of 81 to the Dev channel + - This typically means that the bug is urgent and important, as Dev releases are happening every week and are ok to be a little bit buggy. + +## Out of scope + +### Managing the backlog + +[[Query]](https://bugs.chromium.org/p/chromium/issues/list?q=Hotlist%3DDevTools-Backlog) + +Managing the backlog is out of scope for the triage rotation. The backlog will be groomed continuously by hablich@ for now. The SLA is that there should be a maximum of 50 issues in there. + +### Managing the ProductReview queue + +[[Query]](https://bugs.chromium.org/p/chromium/issues/list?q=Hotlist%3DDevTools-ProductReview) + +Issues in `ProductReview` will continuously be handled by hablich@ to unblock items in there. SLA is max 10 issues. + +## References + +- [Chromium triage guidelines](https://www.chromium.org/for-testers/bug-reporting-guidelines/triage-best-practices) diff --git a/chromium/third_party/devtools-frontend/src/docs/workflows.md b/chromium/third_party/devtools-frontend/src/docs/workflows.md new file mode 100644 index 00000000000..1631949c0ad --- /dev/null +++ b/chromium/third_party/devtools-frontend/src/docs/workflows.md @@ -0,0 +1,276 @@ +# Workflows + +## Checkouts + +In order to make changes to DevTools frontend, build, run, test, and submit changes, several workflows exist. Having [depot_tools](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up) set up is a common prerequisite. + +### Standalone checkout + +As a standalone project, Chrome DevTools frontend can be checked out and built independently from Chromium. The main advantage is not having to check out and build Chromium. + +However, to run layout tests, you need to use the [integrated checkout](#Integrated-checkout). + +#### Checking out source + +To check out the source for DevTools frontend only, follow these steps: + +```bash +mkdir devtools +cd devtools +fetch devtools-frontend +``` + +#### Build + +To build, follow these steps: + +```bash +cd devtools-frontend +gn gen out/Default +autoninja -C out/Default +``` + +The resulting build artifacts can be found in `out/Default/resources/inspector`. + +#### Update to latest + +To update to latest tip of tree version: + +```bash +git fetch origin +git checkout origin/master +gclient sync +``` + +#### 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`. + +##### Running from file system + +This works with Chromium 79 or later. +**(Requires `brew install coreutils` on Mac.)** + +```bash +<path-to-chrome>/chrome --custom-devtools-frontend=file://$(realpath out/Default/resources/inspector) +``` + +Note that `(realpath out/Default/resources/inspector)` expands to the absolute path to build artifacts for DevTools frontend. + +Open DevTools via F12 on Windows/Linux or Cmd+Option+I on Mac. + +Tip: You can inspect DevTools with DevTools by undocking DevTools and then opening a second instance of DevTools (F12 on Windows/Linux, Cmd+Option+I on Mac). + +##### Running from remote URL + +This works with Chromium 85 or later. + +Serve the content of `out/Default/resources/inspector` on a web server, e.g. via `python -m http.server`. + +Then point to that web server when starting Chromium, for example: + +```bash +<path-to-chrome>/chrome --custom-devtools-frontend=http://localhost:8000/ +``` + +Open DevTools via F12 on Windows/Linux or Cmd+Option+I on Mac. + +##### Running in hosted mode + +Serve the content of `out/Default/resources/inspector` on a web server, e.g. via `python -m http.server`. + +Then point to that web server when starting Chromium, for example: + +```bash +<path-to-chrome>/chrome --custom-devtools-frontend=http://localhost:8000/ --remote-debugging-port=9222 +``` + +In a regular Chrome tab, go to the URL `http://localhost:9222#custom=true`. It lists URLs that can be copied to new Chrome tabs to inspect individual debug targets. + +### Integrated checkout + +The integrated workflow offers the best of both worlds, and allows for working on both Chromium and DevTools frontend side-by-side. This is strongly recommended for folks working primarily on DevTools. + +This workflow will ensure that your local setup is equivalent to how Chromium infrastructure tests your change. It comes in two flavors. + +A full [Chromium checkout](#Chromium-checkout) is a pre-requisite for the following steps. + +#### Remove existing devtools-frontend sub-repository + +First, you need to remove the existing devtools-frontend sub-repo from the Chromium checkout in `chromium/src/`. + +In `chromium/src`, run `gclient sync` to make sure you have installed all required submodules. + +```bash +gclient sync +``` + +Then, disable `gclient sync` for DevTools frontend inside of Chromium by editing `.gclient` config. From `chromium/src/`, run + +```bash +vim $(gclient root)/.gclient +``` + +In the `custom_deps` section, insert this line: + +```python +"src/third_party/devtools-frontend/src": None, +``` + +Then run + +```bash +gclient sync -D +``` + +This removes the DevTools frontend dependency. We now create a symlink to refer to the standalone checkout (execute in `chromium/src` and make sure that `third_party/devtools-frontend` exists): + +**(Note that the folder names do NOT include the trailing slash)** + +Following this step, there are two approaches to integrating the standalone devtools. + +#### Flavor 1: separate gclient projects + +The first approach is to have separate gclient projects, one for each repository, and manually +create a symlink. First, get a checkout of [DevTools frontend](#Standalone-checkout). + +To then create the symlink: + +```bash +ln -s path/to/standalone/devtools-frontend third_party/devtools-frontend/src +``` + +Running `gclient sync` in `chromium/src/` will update dependencies for the Chromium checkout. +Running `gclient sync` in `chromium/src/third_party/devtools-frontend/src` will update dependencies for the standalone checkout. + +#### Flavor 2: a single gclient project + +The second approach is to have a single gclient project that automatically gclient sync's all dependencies for both repositories + +After removing your devtools dependency, modify the .gclient file for `chromium/src` +to add the devtools project and a hook to automatically symlink (comments are optional): + +```python +solutions = [ + { + # Chromium src project + "url": "https://chromium.googlesource.com/chromium/src.git", + "managed": False, + "name": "src", + "custom_deps": { + "src/third_party/devtools-frontend/src": None, + }, + "custom_vars": {}, + }, + { + # devtools-frontend project + "name": "devtools-frontend", + "url": "https://chromium.googlesource.com/devtools/devtools-frontend", + "custom_deps": {} + } +] +``` + +Run `gclient sync` once in `chromium/src/` to get the new devtools frontend checkout. + +To automatically symlink between `devtools-frontend` and `chromium/src`, you can add the following +hook to your `.gclient` file to manage your `chromium/src` repository after your list of solutions. + +```python +hooks = [ + { + # Ensure devtools is symlinked in the correct location on every gclient sync + 'name': 'Symlink Depot Tools', + 'pattern': '.', + 'action': [ + 'python', + '<path>/<to>/devtools-frontend/scripts/deps/ensure_symlink.py', + '<path>/<to>/chromium/src', + '<path>/<to>/devtools-frontend' + ], + } +] +``` + +Running `gclient sync` anywhere within `chromium/src/` or `chromium/src/third_party/devtools-frontend/src` will update dependencies for both checkouts. Running `gclient sync -D` will not remove your symlink. + +### Chromium checkout + +DevTools frontend can also be developed as part of the full Chromium checkout. +This workflow can be used to make small patches to DevTools as a Chromium engineer. +However, it is different to our infrastructure setup and how to execute general maintenance work, and therefore discouraged. + +#### Checking out source + +Follow [instructions](https://www.chromium.org/developers/how-tos/get-the-code) to check out Chromium. DevTools frontend can be found under `third_party/devtools-frontend/src/`. + +#### Build + +Refer to [instructions](https://www.chromium.org/developers/how-tos/get-the-code) to build Chromium. To only build DevTools frontend, use `devtools_frontend_resources` as build target. The resulting build artifacts for DevTools frontend can be found in `out/Default/resources/inspector`. + +#### Run + +Run Chrome with bundled DevTools frontend: + +```bash +out/Default/chrome +``` + +## Test + +### DevTools frontend + +Test are available by running scripts in `scripts/test/`. Please refer to the [overview document](https://docs.google.com/document/d/1c2KLKoFMqLB2A9sNAHIhYb70XFyfBUBs5BZSYfQAT-Y/edit). The current test status can be seen at the [test waterfall](https://ci.chromium.org/p/devtools-frontend/g/main/console). + +### Layout tests + +After building content shell as part of Chromium, we can also run layout tests that are relevant for DevTools frontend: + +```bash +autoninja -C out/Default content_shell +third_party/blink/tools/run_web_tests.py http/tests/devtools +``` + +## Creating a change + +Usual [steps](https://chromium.googlesource.com/chromium/src/+/master/docs/contributing.md#creating-a-change) for creating a change work out of the box, when executed in the DevTools frontend repository. + +## Managing dependencies + +- To sync dependencies from Chromium to DevTools frontend, use `scripts/deps/roll_deps.py && npm run generate-protocol-resources`. + +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`. + +## Merges and Cherry-Picks + +_Merge request/approval is handled by Chromium Release Managers. DevTools follows [The Zen of Merge Requests](https://www.chromium.org/developers/the-zen-of-merge-requests). In exceptional +cases please get in touch with hablich@chromium.org._ + +Step-by-step guide on how to merge: + +1. Request and receive approval to merge +1. Backmerges are done to the chromium/xxxx (e.g. chromium/3979) branch respectively on the DevTools frontend repo +1. Use [Omahaproxy](https://omahaproxy.appspot.com/) to find out what + branch a major Chromium version has (column true_branch). + Open the to-be-merged commit in Gerrit e.g. + [Example](https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/1928912) +1. Click hamburger menu on the top right and select Cherry Pick +1. Select branch to merge to e.g. chromium/3968 +1. Cherry Pick CL is created e.g. + [Example](https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/1928913) +1. Get it reviewed if necessary +1. Click hamburger menu on the cherry pick CL and select Submit +1. Done + +## Useful Commands + +### `git cl format --js` + +Formats all code using clang-format. + +### `npm run check` + +Runs all static analysis checks on DevTools code. |