You do not need to use this process if:- Your change does not affect web API behavior to the point that developers need to be aware of it (i.e. their site might change behavior).
- Your change is trivial and your reviewer agrees
- You must still create a chromestatus entry for the feature if none exists or update any existing entry.
- Your team has received explicit permission not to use this process
- You must still create a chromestatus entry
- Send a "Web-Facing Change PSA" email to chromium-dev@ (CC blink-dev@)
Frequently asked questions
Q: Do I need any of this if my project is just refactoring or re-architecting the code? Do the API owners need to be involved?
A: No. The API owners oversee the process of shipping web-exposed API changes. They are not necessarily leads or overseers of any of the code. Instead, you should get the buy-in of the leads of the code areas touched by your project. In addition, such large projects should have public design docs that are also shared on blink-dev@chromium.org (or chromium-dev@chromium.org, for projects that have significant parts outside of third_party/blink) for feedback (this is also a good way to get the attention of relevant leads you might not have thought of).
For code-related questions, you can email platform-architecture-dev@chromium.org in addition to blink-dev@ as a catch-all option when the code ownership is not clear or the feature needs large-scale refactoring changes.
Q: What if I want to add some code to third_party/blink that is for a non-web-exposed feature? Is that allowed?
A: In general, no. On a case-by-case basis an exception could be given if there is no other reasonable way to implement the feature. Ask for permission from leads of the code area as well as the API owners. (The API owners need to be involved only to help understand if the feature really is not web-exposed; this can be a very subtle question.)
Q: I am not sure of the right approach for my feature. What should I do?
A: Please reach out to the API owners for help! While they are not gatekeepers for everything, they are very happy to give advice and unblock your feature. An email to blink-api-owners-discuss@chromium.org is the best way; if a public-facing email is not possible, please email the API owners directly.
The process to launch a new featureThe recommended tasks in the intent process are broken down by phases in the Blink feature development lifecycle: Idea, Design and Implementation and Post-launch.
Note: The only strictly required gate to this process are the 3 LGTMs from API_OWNERS on an intent-to-ship. Smaller changes may skip some steps in the process, however, considering all the steps listed below will maximize your chance of success on an intent-to-ship and reduce the risk of having to undo/redo parts of your design or implementation. Idea PhaseTasks: Discuss idea with team/team lead (TL) or area expert that this work is in scope of Write an explainer (or a brief design doc, if the feature does not warrant an explainer, for example, a minor change to a mature spec) Send an (early) intent to Prototype (i2p) to blink-dev@ and address feedback (this used to be called "Intent to Implement".) Request an API mentor (do you need one?) for guidance while designing the API. Please have a Google employee make this request for you, if you need one.
Gates: Informal support from TL to work on this project
Outputs: Design PhaseTasks: Expand the explainer into a design doc (this may also have implementation-specific details) Work with the API mentor (if you requested/assigned one) or request one if the design work turned out to be more complex than you thought Start working on any spec changes (The complete standardization process is out of scope for this document. For Googlers, start here.) Request TAG design consulting (you don’t need a spec for this request) and include a link to the issue in the intent-to-implement. If you have any time constraints or deadlines, please specify those when you make this request (length of consulting depends on complexity, from a few weeks to months, so starting early is highly recommended!)
Update the Intent-to-prototype thread with the design doc Some launches require a formal Chrome launch review (bug template) (especially if your feature has security, privacy, legal, or UI implications) Optional: experiment with a prototype implementation (JS polyfill and/or blink code not intended for review/landing)
Gates: Addressed any major feedback from TAG design consulting, API mentor and blink-dev@
Outputs: Implementation PhaseTasks: Start turning design doc into implementation. Note that any CLs landing at this stage should be runtime enabled features. Consider adding a UseCounter to track usage of your new feature in the wild. Write integration tests for your feature as web-platform-tests. Continue to work with your API mentor/TAG consulting if there are any design changes If there are significant design changes since the i2p, please update the i2p thread with the current design doc. This helps ensure there are no surprises in feedback on the intent-to-ship. (Send an intent to experiment if you need to start an origin trial. Please note that origin trials are not exempt from requiring cross-functional approvals from the Chrome launch review process. Details here.) You should have a TAG sign-off by now, or have ongoing discussions on the TAG review without any outstanding major concerns. Include a link to the TAG issue in the intent-to-ship. Send an intent to ship (i2s) to blink-dev@ Update chromestatus with target milestones (remember to keep this updated, if things change) Address any feedback. Once you have 3 LGTMs from API_OWNERS, you may enable the feature by default. See here for the principles the API owners will apply in evaluating whether the feature is mature enough to ship. (API OWNERS requirements are listed here.) Let web developers know about your feature. (Developer Relations, actually. If you've done things correctly, your work will be minimal, if required at all.)
Gates: 3 LGTMs from API_owners (email blink-api-owners-discuss@chromium.org or reach out to one of the API owners if no open/unaddressed feedback and blocked on LGTMs after 5 days)
Outputs: Working, tested and verified code Tests landed in web-platform-tests (or explanation for why that's not practical) 3 LGTMs from api-owners@ Feature enabled by default
Post LaunchWatch for crashes, regressions caused by your feature and any substantive spec feedback. Review UseCounter and other metrics. Update the intent-to-ship if non-trivial issues (like web compatibility or serious design questions) arise. When in doubt, email blink-dev@ (or blink-api-owners-discuss@ if you prefer a small audience) for advice. Once the API is on by default, continue to support other implementations (for instance, clarifying the spec, improving the tests, fixing bugs, updating support status in chromestatus) until the feature is broadly supported and works the same across engines. Remember, your job is to move the web forward, not simply make Chrome better. Review MDN docs for technical accuracy and clarity. Feel free to make edits directly or reach out to jmedley@. When you are convinced enabling the feature by default has “stuck”, remove any unused code including RuntimeEnabledFeatures entries.
[1] Origin trials should be run for a specific reason. These questions are guidance to identifying that reason. However, there is still debate about the right reasons, so the guidance may change. You can join the conversation in this doc.
For an overview, and explanation of motivations, please see: |
