Chromium Specification Mentors

Quick links: spec-mentors@chromium.org Google Group; mentor request form

This program is not yet active

This page is being drafted here on chromium.org but the associated program has not yet launched. So, you should probably ignore it for now.

Introduction

Introducing a new feature to the web platform requires writing a specification, which is a separate skill set from writing code. It involves API design, cross-company collaboration, and balancing the needs of the web's various stakeholders.

Specification mentors apply their experience in this area to ensure that explainers and specifications put out by the Chromium project are of high quality and ready to present to the world. For folks new to the standardization process, mentors can provide guidance and review. And for those who are already experienced, mentors provide the equivalent of code review: a second perspective to help raise questions early or spot things you might have missed.

This process aims to improve the quality of explainers and specifications, and thus uphold the Chromium project's commitment to an open, interoperable, and well-designed web platform. It should also make the process of launching a new feature more predictable and less painful for Chromium engineers.

How we work

General availability

If you have an explainer or spec you'd like some mentorship on or review of, the spec mentors are available at any time. Send us an email at spec-mentors@chromium.org with links to what you're working on, and we can take a look.

Pairing up with your mentor

Before sending an Intent to Prototype, you are encouraged to find a spec mentor to work with. They can review your explainer, as well as the Intent to Prototype itself, to make sure your feature is presenting a good face to the world.

For Googlers, a specification mentor is required at this stage. For other Chromium contributors, you're welcome to reach out if you find one helpful.

To find a specification mentor, you can draw upon your existing contacts (e.g., your team lead or coworkers), or you can fill out our form with the relevant information. In the latter case, we will get back to you with a proposed mentor within 2 business days; we want to make sure your Intent to Prototype proceeds as quickly as possible.

What to expect

Your mentor will be available for you to ask questions or ask for reviews throughout the lifetime of your feature. In particular, if you would like someone to review your explainer or specification work, you can collaborate with them directly, e.g. using video calls, GitHub pull request reviews, or Google Docs.

There are three specific points at which you'll want to request detailed review from your mentor, so that they can help ensure that your public artifacts are high-quality:

  1. (Optional) For your explainer, before sending it out in an Intent to Prototype.

  2. For your explainer and specification, before beginning a Dev Trial and sending these artifacts off to wide review groups and other browser vendors.

  3. For your specification, before sending an Intent to Ship.

The Chrome Platform Status tool, and the Intents they generate, will include explicit lines asking for your standardization mentor's signoff at these points.

Your mentor can optionally reply to the Intent to Prototype or Intent to Ship threads with a summary of how the review went. Assuming the review went well, this can help bolster the API owners' confidence in the specification. For example:

"The use cases for this feature make a lot of sense. I raised an issue to consider some alternate approaches, and noted a potential privacy risk that should be at least discussed, and ideally mitigated. We agreed to keep these in mind as the prototyping progresses."

or

"This feature and the proposed API both look good to ship from my perspective. I filed a series of small issues on potential API improvements, which have been incorporated. And we tightened up the specification language around the X algorithm, which now has extensive web platform tests for the previously-ambiguous edge cases."

If all goes well, then by the time you reach the Intent to Ship stage, your explainer and spec will have been refined through mentorship and review to be the best they can be. This will put you in a strong position with regard to some of the most-often-problematic parts of the Intent to Ship, such as the the Interoperability & Compatibility risks section, and thus smooth the path toward API OWNER approval.

Can I join?

Yes, please do! Becoming proficient in design reviews is a core engineering skill, and one of the best ways to do that is to help other Chromium project members with their explainers and specifications. And it's important for the health of the Chromium community to have as many engineers as possible who understand and can work successfully within the standards process.

If you've ever written an explainer or specification before, you've probably gotten a good amount of feedback from various audiences, both internal and external. That means you're qualified to help others through the same process, to pass on what you have learned. You won't be alone: the other mentors are around to help with anything you're not sure of.

To join the program and start getting assigned features to help mentor, subscribe to our mailing list, at spec-mentors@chromium.org. When new features come in, feel free to reply that you'd be willing to help; otherwise, domenic@chromium.org will assign features to mentors according to his best judgment.

Comments