Web Platform Changes: Guidelines

In addition to making the web platform faster and more secure, improving the web platform also means adding new functionality and removing cruft. To fulfill our good citizenship mission, we need to be careful to change the web-facing API in a transparent, responsible, and compatible manner. We measure success as moving the open web platform forward as a whole, not just moving one implementation forward.

In practice, we strive to ensure that the features we ship by default have open standards. As we work on features, we track their progress in the web standards community with the Chromium Features Dashboard, which lets us be transparent about the status of each feature and about how we make decisions about which features to enable by default for the open web.


These guidelines cover non-trivial changes that are exposed to the open web or in some other way have implications for web developers, including changes that add or remove functionality or APIs. Changes that are not exposed to the open web (e.g., user interface features, extension APIs, or testing infrastructure) are outside the scope of this policy.

Policy for shipping and removing web platform API features

As browser developers, we find that there’s often tension between moving the web forward and preserving compatibility. On 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. By definition, when any vendor ships a new feature (or is the first to remove an obsolete feature), the API change is not yet interoperable, so cross-browser compatibility is sacrificed, even if briefly. This section outlines our approach to resolving this tension.

Evaluating “interoperability and compatibility risk”

Interoperability risk is the risk that browsers will not eventually converge on an interoperable implementation of the API. Interoperability at a given time point is not a well-formed concept, because unless every browser shipped new features at exactly the same time then there is a period of non-interoperability. In practice, we forecast “interoperability risk” (a) by observing the public behavior of others in the web ecosystem. Heuristics that decrease risk a priori for an unshipped feature include, in rough order of importance:
  • Other vendors already shipping interoperable implementations
  • A mature specification in the relevant standards body
  • A shared test suite for that specification
  • Positive signals from other browser vendors
  • Lack of negative signals from other browser vendors
See the Blink principles of interoperability for an in-depth discussion of these considerations.

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 is also a factor when adding new features (e.g. Unprefixed CSS Animations). See the Blink principles of web compatibility and tools used to evaluate and weigh compatibility risk, though given the complexity and nuance individual engineers are not expected to be familiar with the details.

Evaluating “moving the web forward”

A change to Blink’s API surface is said to “move the web forward” if it either (a) enables developers to build compelling applications for a large number of users, both now and in the future, and/or (b) reduces code complexity in Blink or Chromium.

Bucket (a) is subjective and changes over time. In 2014, we believe the most important changes for developers---and, by extension, users---are those that make the web more performant and easier to use on mobile devices. For more information, see the 2014 Blink goals brainstorming thread.

Bucket (b) is important to make sure that the web’s progress is not overly constrained by its legacy. Simplifying the codebase allows us to make performance improvements, more quickly add more important features, and reduce binary size. In most cases, we believe these benefits will extend to other browsers as well.

Balancing “moving the web forward” and “interoperability and compatibility risk”

To manage the project-wide tension between moving the web forward and interoperability and compatibility, we ask of each proposed API change: does this individual change strike the right balance between making the web better and minimizing interoperability and compatibility risk?

In an ideal world, all changes would both drastically move the web forward and involve zero interoperability and compatibility risk. In practice, this is rarely the case; features fit somewhere else on this chart:

Blink’s willingness to accept a change is largely determined by the change’s location on the chart above:
  • If a change has low interoperability and compatibility risk and significantly moves the web forward, Blink usually welcomes it (e.g., shipping unprefixed CSS Transforms).
  • If a change has low interoperability and compatibility risk but isn’t expected to significantly move the web forward, Blink usually still welcomes it. Occasionally, Blink will reject changes in this bucket to avoid technical complexity (e.g., not shipping our old implementation of CSS Variables).
  • If a change has high interoperability risk and isn’t expected to significantly move the web forward, Blink will usually not welcome it (e.g., not shipping canvas supportsContext).
  • If a change has high interoperability risk but is expected to significantly move the web forward, Blink will sometimes welcome it after careful, publicly-explained consideration (e.g. shipping Shadow DOM). In such cases, the implementer is expected to:
    • Propose an editor’s draft (or equivalent) to the relevant standards group.
    • Discuss the feature publicly with implementers of other browser engines.
    • Take on an active commitment to shepherd the feature through the standards process, accepting the burden of possible API changes.
Of course, equal minds can disagree about the fuzzier aspects of these policies. For example, if a change increases runtime performance but consumes more battery, does it “move the web forward”? Or: what combination of the heuristics above precisely constitutes “high” compatibility risk?

To equitably resolve these kinds of questions on a per-change basis, Blink has a well-defined process for discussing and approving web-facing API changes. It consists of code reviews, announcements to blink-dev, and formal API review meetings. The most formal requirement of the process is that API changes must receive an LGTM from at least three different API owners before enabled by default on trunk. The API owners are responsible for making sure the policy described above is applied appropriately on a per-change basis.

Trivial Changes

Trivial platform changes do not need to meet the requirements above. For example, changes to existing APIs to improve compliance with web standards or to fix bugs are welcome. When in doubt, please send at a PSA to blink-dev or ask an API OWNER for advice.

However, any new API (no matter how small) is considered non-trivial. Trivial changes should be small fixes that have low risk of disrupting web developers. Trivial changes should be labeled as such in their code review, and may still require the LGTM of one API OWNER if they change the stable-build output of the webexposed tests.

If we’re unsure about the extent to which a change will impact web developers, we may ask the contributor proposing the change to provide data quantifying the impact. If a project member questions whether a change is trivial, we will err on the side of caution and ask the contributor to meet the requirements above.

Vendor Prefixes

Historically, browsers have relied on vendor prefixes (e.g., -webkit-feature) to ship experimental features to web developers. This approach can be harmful to compatibility because web content comes to rely upon these vendor-prefixed names. Going forward, instead of enabling a feature by default with a vendor prefix, we will instead keep the (unprefixed) feature behind the “enable experimental web platform features” flag in about:flags until the feature is ready to be enabled by default or exposed for a limited duration origin trial.