[docs] Add a skeleton for the Contribution Guide.

Bug: 354102605
Change-Id: I8f253844aeae4a386f967140a472f4ee12b666f3
Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/5803966
Auto-Submit: Benedikt Meurer <[email protected]>
Reviewed-by: Philip Pfaffe <[email protected]>
Commit-Queue: Benedikt Meurer <[email protected]>

Author: bmeurer

CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing to Chromium DevTools
+
+Contributions to Chromium DevTools include code, documentation, and responding
+to user questions.
+
+See the [Chrome DevTools Contribution Guide](./docs/contributing/README.md)
+for details on how you can contribute. Also checkout the [Contributing to
+Chromium](https://chromium.googlesource.com/chromium/src/+/main/docs/contributing.md)
+and [Contributing to V8](https://v8.dev/docs/contribute) documents for details
+how to contribute to the Chromium / V8 code base in general, which is relevant
+when working on the DevTools back-end.

README.md

@@ -22,7 +22,6 @@ maintain a DevTools front-end checkout, as well as design guidelines, and archit
 - [awesome-chrome-devtools](https://github.com/paulirish/awesome-chrome-devtools): recommended tools and resources
 - Contributing to DevTools: [bit.ly/devtools-contribution-guide](https://goo.gle/devtools-contribution-guide)
 - Contributing To Chrome DevTools Protocol: [docs.google.com](https://goo.gle/devtools-contribution-guide-cdp)
-- DevTools Design Review Guidelines: [design_guidelines.md](docs/design_guidelines.md)
 
 ### Source mirrors
 

docs/README.md

@@ -23,15 +23,13 @@ below.**
 
 ### General Development
 
-*   [Get the Code](get_the_code.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)
-*   [Contributing Changes](contributing_changes.md)
-*   [Chrome DevTools Design Review Guidelines](design_guidelines.md)
 *   [Release Management](release_management.md)
 *   [Dependencies](dependencies.md)
 *   [Localization](l10n.md)
-*   [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)
@@ -41,11 +39,12 @@ below.**
 ### Architectural Documentation
 
 *   [Architecture of DevTools](architecture_of_devtools.md)
+*   [Chrome DevTools Protocol (CDP)](devtools-protocol.md)
 *   [Resource management in DevTools](resource_management.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

docs/contributing/README.md

@@ -0,0 +1,45 @@
+# 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. [Design Documents](./design.md)
+1. [Contributing changes](./changes.md)
+
+## 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 <https://chromium-review.googlesource.com>
+-   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.

docs/contributing/changes.md

@@ -0,0 +1,87 @@
+# 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.
+
+[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 [email protected]._
+
+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 <https://chromiumdash.appspot.com/branches> 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.
+

docs/contributing/design.md

@@ -0,0 +1,165 @@
+# 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)).
+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
+[[email protected]](mailto:[email protected]) and
+[[email protected]](mailto:[email protected]). And they need to
+be send to
+[[email protected]](mailto:[email protected]).
+
+Google internal design docs have to live in the
+[Design Documents (internal)](https://drive.google.com/corp/drive/folders/15oHN9vX8j08QOkegjWKdSN0XjyaoLanl)
+folder of the shared internal
+[Chrome DevTools](http://go/chrome-devtools/team-resources#chrome-devtools-shared-drive) team drive, and
+should be sent to
+[[email protected]](mailto:[email protected]).
+
+*** note
+**IMPORTANT (Googlers):** Every design document (whether public or internal) must be editable
+by [[email protected]](mailto:[email protected]) and
+must have a `go/chrome-devtools:<project-name>-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 ([email protected]). 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 [email protected] (make sure to give comment access to [email protected], 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 <reason>" 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.

docs/design_guidelines.png renamed to docs/contributing/images/design-guidelines.png

@@ -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]