Web Platform Changes: Our Values

Introduction

The Chromium project's ultimate goal is to move the web platform forward. We do this by shipping features that bring user benefit.

Unlike many other platforms, the web has multiple implementations. The Chromium project's primary lever for improving the experience of web users is by improving our implementation, and thus shipping features to our users directly. But we strive to do so in a way that also helps other implementations, and thus increases the interoperable surface area of the web and improves the experience of those users we do not directly serve.

The Chromium project has been blessed with a large ecosystem of active contributors. As such, we can take on the responsibility of proving out features in our engine first, trialing them with Chrome users ahead of general deployment across all engines and to more web users. While we do so, it is imperative that we deliver the feature in a way that invites broad feedback, and makes it easy for other engines to implement if they decide the proposal is valuable for their users.

This document outlines how the Chromium project thinks about moving the web forward, and the reasoning behind the various processes and requirements we place on members of the Chromium community as part of the Blink launch process.

Finding balance

For all browser developers, there is an inherent tension between moving the web forward and preserving interoperability and compatibility. One the one hand, the web platform API surface must evolve to stay relevant. On the other hand, the web's primary strength is its reach, which is largely a function of interoperability. And by definition, when any browser ships a new feature, the API change is not yet interoperable. So we need to balance some key risks while we improve the web platform.

Interoperability risk is the risk that browsers will not eventually converge on an interoperable implementation of the proposed feature. Interoperability cannot be determined only at a given point in time; since browsers ship features at different times, there is always a degree of non-interoperability on the web. Instead, we are concerned with long-term interoperability risk, which we forecast by observing the public behaviors of others in the web ecosystem, and we work to minimize via the launch artifacts discussed below. See the Blink principles of interoperability for a more in-depth discussion.

Compatibility risk is the likelihood that a change will break existing web content loaded in Chromium. Compatibility risk is especially common with API removal, but it is also a factor when adding new features: before shipping, we need to be as sure as we reasonably can that the feature will not change or evolve in backward-incompatible ways in the future, as such incompatible changes cause direct harm to our users. Additionally, there can be cases where even new features interact with old ones to cause strange compatibility issues. See the Blink principles of web compatibility and Web compat analysis tools for more on this subject.

In an ideal world, all changes would both dramatically move the web forward, and involve zero interoperability and compatibility risk. In practice, this is rarely the case, and a tradeoff needs to be made:

  • If a change has low interop/compat risk and significantly moves the web forward, Chromium welcomes it. (Example: shipping CSS Grid.)

  • If a change has low interop/compat risk but isn't expected to significantly move the web forward, Chromium usually still welcomes it. (Example: moving prefixed event handler properties around.) Occasionally, Chromium will reject changes in this bucket to avoid technical complexity (e.g., removing our implementation of KV Storage).

  • If a change has high interop/compat risk and isn't expected to significantly move the web forward, Chromium will usually not welcome it. (Example: not shipping canvas supportsContext.)

  • If a change has high interop/compat risk but is expected to significantly move the web forward, Chromium will sometimes welcome it after a careful, publicly-considered explanation, accompanied by the artifacts discussed below. (Example: shipping WebUSB.)

The role of the API OWNERS

To find this balance and resolve the above tradeoffs on a per-change basis, Chromium delegates to a trusted group, the Blink API OWNERS, to decide what web platform features are delivered to our users. Concretely, they are the final approvers in the Blink process, where Chromium contributors present a series of artifacts as part of their Intent to Prototype/Experiment/Ship.

These artifacts are a key part of the process, and much of the rest of this document is spent detailing them and why we think they are important enough to make them requirements before shipping a feature. Because of the amount of resources committed to driving the web forward through Chromium, we accept that the bar should be higher for us—we can't expect, time and again, that the burden of designing new features will be split equally with others. So, we need to do as much as we can to set up and encourage others to participate.

We have not always done this perfectly in the past, and to be honest, it’s unlikely we’ll always do it perfectly in the future. But we commit to trying to work well with others—even when we are implementing features ahead of others.

Launch artifacts that Chromium values

Explainers

Explainers are a proposal's first contact with the world. Well-written and comprehensive explainers help other interested parties judge the value of a feature, by presenting the use cases, the research, and the tradeoffs involved in the design space. Notably, an explainer needs to assume minimal previous domain knowledge in order to serve these goals well.

In particular, an explainer should present a living record of:

  • What problem we are solving.

  • Why we think that problem is important to solve.

  • What the impact of solving the problem would be.

  • Over time, the explainer will develop a specific solution proposal, with supporting arguments for why that proposal is the best among alternatives.

  • Detailed discussion of any concerns raised by other implementers or by wide-review groups, summing up any open questions or conclusions reached. (This often ends up in the "FAQ" or "Alternatives considered" sections, or in other natural locations like the "Security and privacy considerations".)

Explainers should be documents that other implementers can easily read or skim to figure out whether they think a feature is worth investing in. If these other implementers have the time to do so, an explainer repository also serves as an entry point for them to engage in the early design process. Such early engagement is excellent news: it increases the chance of the feature launching to other engines' users, sooner.

Specifications

A good specification is critical to other implementations being able to interoperably implement a feature, and to that feature eventually reaching users of those other implementations. Although our code is open source, and in theory anyone could implement based on it, good specifications have the following benefits:

  • Specifications operate at a higher level than source code, using implementation-agnostic abstractions. Thus, an implementer working on any implementation can read a specification and understand how it would map to their implementation, separate from the Chromium one.

  • Similarly, specifications are reviewable by non-implementers, including web developers and groups providing wide review. Writing a specification makes it easier to capture the input of such groups.

  • Writing a specification crystalizes what the intended behavior is, separate from the implemented behavior.

  • Specifications provide a mechanism for IPR coverage. The amount of coverage varies depending on specification venue, but most venues at the very least guarantee that the specification writers' organization grants a patent license to implement the specification.

Note: the venue for a specification, and whether it is a "specification" (individual unofficial draft, W3C CG draft, TC39 stage 2...) or a "standard" (W3C Recommendation, WHATWG Living Standard, Ecma Standard, ...), only impact the last of these bullet points. As such, it's most important that we write a good specification. The venue and formal status are helpful for gathering IPR coverage, but otherwise should not be a focus.

As such, Chromium developers must ensure that any feature they intend to ship is backed by a complete and thorough specification. This specification must be at the level of detail that the feature can be interoperably implemented in a second engine, should that engine want to bring the feature in question to their users.

Getting this right can be difficult. Generally, a prototype implementation comes before a specification, since it is easier to iterate on the prototype and gather real-world feedback that way. If such prototyping drastically changes the shape of the feature, or results in scrapping the feature altogether, this can save a lot of specification-writing time!

But this ordering does have one disadvantage. Since there was never a point at which the Chromium engineer implemented the feature from scratch, following the specification, we never get a formal check that the specification is complete and detailed enough. This can lead to problems where, when a second implementation does try to implement from scratch, they find the specification incomplete, or find that the specification relies on Chromium-specific assumptions.

To help address this, we have the Chromium Specification Mentors program, which pairs Chromium developers with a trusted mentor to get a second set of eyes.

Finally, the most important part of specification writing is to keep up active maintenance of the specification even after Chromium ships the feature. This is especially true if a second implementer starts implementing and filing bugs based on their experience.

Tests

By contributing web platform tests for our proposals, we create a machine-checkable subset of the specification. In practice, this is essential to achieving interoperable implementations, as well as ensuring compatibility through preventing regressions. Of note is the wpt.fyi dashboard, which enables in-depth comparison of cross-browser results and a resulting drive toward interoperability.

Additionally, by devoting the Chromium project's resources to writing web platform tests, we ensure that other implementations have a ready-made test suite when they go to implement the feature. This is excellent leverage: we can invest our resources in writing the tests, but they can be used by all future implementations as well, almost for free.

Chromium developers should strive for high levels of coverage for their feature's web platform tests suite. Ideally, something like 100% coverage of both "spec lines" and Chromium code would ensure that Chromium implements the spec faithfully, and that others will be able to leverage the tests to implement the spec in the same way. Some sample test suites which approach this goal include url/, streams/, and pointerevents/.

In practice, this is a hard goal to reach. We can try to approach it by annotating specifications with their associated tests, and running the appropriate Chromium code coverage tools. Another hurdle is that some things are not testable with current infrastructure. We have a dedicated team, ecosystem-infra@chromium.org, which works to improve our testing infrastructure and mitigate such gaps.

Web developer and end user feedback

The best evidence for the value of a feature is testimonials or data from users and web developers. Before launch, these can be gathered in a variety of ways, including Dev Trials, Origin Trials, or direct user and developer engagement in venues like the Chromium or specification issue tracker. After launch, metrics such as use counters can show how much uptake a feature is getting in the wild.

Collating this information together for easy consumption is an important final step in the process before shipping. The goal is to present a body of evidence that makes it easy for other engines to evaluate whether they would like to bring the proposal to their implementation, or not.

Wide review

There are specific groups, usually in the specification ecosystem, which are dedicated to reviewing feature proposals. The W3C TAG is one such group, whose reviews have a formal place in the Blink launch process. But the more such reviews we can gather, the better.

Other groups to consider are:

  • Relevant working groups or specification editors, e.g. the CSSWG for CSS feature proposals; the HTML Standard editors for HTML feature proposals; etc.

  • Cross-functional W3C groups such as the Internationalization WG, Privacy IG, or APA WG.

  • Chromium cross-functional review groups, such as the security, privacy, permissions, and anti-tracking teams.

  • Directly reaching out to other browser engine implementers or standards engineers for their signals.

None of these groups are obligated to respond; many are busy with other reviews or with their own work. But we always attempt to reach out, and respond to any concerns or questions raised. And then we work to capture any answers, or resultant changes, in a permanent location like the specification or explainer.

Conclusion

Notably, these guidelines do not have an explicit requirement that a feature be standardized (as opposed to specified), or that a feature have multi-implementer consensus. Instead, factors like those are inputs into the overall evaluation. Indeed, all engines implement features ahead of others, or ahead of formal standardization. (See the "Browser-Specific" section of the Web API Confluence Dashboard.) But our process requires significant up-front investment from Chromium contributors before a feature is considered ready to ship.

Even if other browsers have not yet implemented a feature, these artifacts are important to the Chromium project. Creating solid explainers, specs, and tests, and gathering feedback and wide review, can move us toward future interoperability, and decrease the risk in the eyes of the API OWNERS. Indeed, even if other browsers are opposed to a feature, by taking the steps above, we can confidently state that we minimized risk, and layed out a well-lit path in case the other browsers change their evaluation or their priorities in the future.

Comments