docs/cookbook/create_new_issues.md - devtools/devtools-frontend.git - Git at Google

 # 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.
	# 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.