Apply governance change
DISABLE_THIRD_PARTY_CHECK=no code changes
[email protected]
Change-Id: I2477c36f5ef2494ccae3efae3f1aee942f365fec
Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/2489420
Auto-Submit: Yang Guo <[email protected]>
Reviewed-by: Paul Lewis <[email protected]>
Commit-Queue: Yang Guo <[email protected]>
diff --git a/docs/design_guidelines.md b/docs/design_guidelines.md
index 641946f..b5909d7 100644
--- a/docs/design_guidelines.md
+++ b/docs/design_guidelines.md
@@ -1,13 +1,8 @@
# 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:
+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.
-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
+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:**
@@ -15,15 +10,6 @@
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)
@@ -32,82 +18,58 @@
This person is the creator of the feature and the creator of the design documentation.
-### The Technical Leads (TL)
+### Technical Lead (TL)
-_LGTM_: Must have
+_LGTM_: Required. May delegate.
-An LGTM is needed from the DevTools TLs, which are Benedikt Meurer ([email protected]) and Rob Paveza ([email protected]) 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.
+The Chrome DevTools TL is Benedikt Meurer ([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 TLs, the EnReOw takes over the responsibility.
+In the absence of the TL, an EnReOw can act in their stead.
### LGTM provider
-_LGTM_: Must have
+_LGTM_: Required. May delegate.
-This is a person that is required to give LGTM. These are usually ICs which have significant knowledge about the areas in question.
+This is a person that is required to give LGTM. These are usually ICs with significant knowledge about the areas in question.
-### “Random” reviewer of the document (RRotD)
+### Reviewer
-_LGTM_: Not required
+_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.
+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
+_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/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.
+
+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 [email protected] (please make sure to give comment access to [email protected], 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 [email protected] (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 themselves 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.
+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 master branch. Note that a series of small incremental changes has a higher chance of receiving timely reviews and actionable feedback.
## FAQ
-### How to decide if the feature is worthy to have a design document?
+### Is it worth creating a design document?
-Some pointers when a design doc is appropriate:
+It is always useful to have a design document. Its length can vary depending on the scope of the proposed change.
-- 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.
+### 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?
@@ -119,13 +81,13 @@
### Where can I find a template for design documents?
-[Here](http://bit.ly/devtools-design-doc-template).
+[Here](https://bit.ly/devtools-design-doc-template).
-### What if something big changes?
+### What if I made big changes to the design document?
-Make sure you still have the LGTMs e.g. by pinging the LGTM providers with a clear, reasonable deadline to veto.
+Make sure you still have the LGTMs e.g. by pinging the LGTM providers.
-### LGTM providers don’t comment on my doc, what should I do?
+### LGTM providers do not comment on my design document, what should I do?
In this case you can follow this path of escalation:
@@ -135,9 +97,10 @@
### 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.
+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 [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.
+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.
