Create new Issues in DevTools
The goal of this doc is to guide you through the necessary steps to send messages to the new Issues panel (Design Doc). 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@ (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:
- Use the generic issue. 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. - If a generic issue is not enough, you can introduce a domain/problem specific issue type. See here 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.
- 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 for the browser side
- here for the renderer side
- Please add the corresponding backend and frontend test for your changes.
- Example of a CL introducing backend web_tests.
- Example of a CL introducing frontend E2E tests.
- Please CC szuend@ 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@ and the rest of your team for approval.
- Once the issue strings are reviewed, implement the front-end CL following this example. Please add szuend@ 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, backend example CL).
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 for reference). You can wordsmith the issue description in a separate docs or directly in the CL with Gerrit.
