Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Web Platform Backward Compatibility

Concept

Vocabulary that names a phenomenon.

Chromium treats backward compatibility on the open web as a hard constraint: code that worked in a prior Chrome version keeps working unless the project deliberately removes it through a gated, public deprecation process.

A site that loaded successfully in Chrome 119 should still load in Chrome 120, 121, and 122. A library that ran in production three years ago should not fail because Chrome shipped a milestone. That standing claim is what the Chromium project makes whenever it adds or removes web-platform surface. UseCounters, Intent threads, deprecation trials, Chrome Platform Status entries, and developer warnings make the claim binding rather than aspirational.

The principle surprises engineers from monolithic-codebase backgrounds because the cost is real. A deprecated API can remain in the source tree for years after the feature team is done with it. Removal is gated by measured usage and public review, not by the team’s preference. Even a cleanup whose value is not in dispute can take many milestones to reach users. The project absorbs that cost because the alternative is worse: a browser whose updates routinely break pages would force every site operator to test every release before deployment. A web platform where that became normal would lose the property that makes it a platform at all.

What It Is

The web-platform backward-compatibility commitment has three operational properties. It binds across the platform’s full API surface: DOM, CSS, JavaScript built-ins, HTTP semantics, and web standards APIs. It is tested against real usage on the open web, not against a benchmark or compliance suite. It can be broken only through a documented procedural path that exposes the cost to public review.

The mechanism that makes the commitment empirical is the UseCounter system. A removable web-platform API is instrumented at the Blink layer so Chromium can count real-world invocations. The counts are aggregated across the install base, reported through the public chromestatus.com feature-popularity surface, and read by API owners when an Intent to Deprecate or Intent to Remove is filed. A feature whose usage remains too high is not removed merely because the feature team wants the code gone. The removal threshold is set in public discussion for the feature at hand; the key fact is that the decision rests on measured web usage, not on taste.

The mechanism that makes the commitment procedural is the symmetric pipeline. The Intent process gates feature addition through Intent to Prototype, Intent to Experiment, and Intent to Ship. It gates removal through Intent to Deprecate and Intent to Remove. The deprecation-trial machinery sits between those Intents when dependent sites need more time: Chrome disables the feature by default, while registered origins can temporarily re-enable it with an origin-trial token. Removal is no easier than addition. On many milestones it is harder, because the addition-side API-owner LGTMs evaluate a hypothetical compatibility cost while the removal-side LGTMs evaluate a measured one.

The commitment is not absolute. A security regression in a deployed feature may need a security patch on the next milestone, an emergency release outside the cadence, or rarely a Finch kill switch. A deliberate spec change travels through standards bodies before Chromium implements the updated behavior. A feature that was available only behind an Origin Trial, runtime flag, or enterprise policy does not carry the Stable-channel commitment for that gated period. The commitment applies once the feature defaults on for Stable users. After that point, every exit from default behavior must travel through a procedural form whose cost matches the dependent population the change will affect.

Why It Matters

Naming the commitment changes how Chromium feature-removal discussions read. An Intent to Deprecate is not a unilateral break notice. It is a calibrated proposal with usage data, a timeline, and a public review path. That distinction matters for downstream release policy: the relevant surfaces are the UseCounter trend, the Chrome Platform Status entry, the deprecation-trial window if one exists, and the target removal milestone.

The commitment binds because the trust-boundary claim binds. A feature that has reached Stable remains available to dependent sites unless the project deliberately and visibly deprecates it. The Deprecation Trial machinery exists for the cases where removal is justified but the dependent population needs a migration window. That cost is also why new web-platform additions are gated more heavily than additions in a typical software product. An addition that reaches Stable acquires the commitment, and the commitment is what makes removal expensive. The Intent to Ship gate is partly a gate against compatibility cost the project may pay forever.

The commitment also names what fails when it fails. The Experiment That Became Permanent antipattern is the case where a trial-scale commitment grows into a Stable-scale dependent population without the same addition-side gate. The Privacy Sandbox third-party-cookies sequence is the large-scale instance. The trial’s dependent population spread across advertising and analytics infrastructure; the original removal plan then collided with the compatibility cost the trial had accrued. The April 2024 decision to route third-party-cookie removal through a user prompt rather than a unilateral flip was the project recognizing that the commitment had become binding in fact.

For an enterprise organization deploying a Chromium-based product, the commitment is what makes “track upstream Stable” a tractable plan. The downstream vendor expects that an upstream Chrome milestone will not silently break a working API surface in the product. A vendor whose risk model treats every milestone as a likely break event over-invests in compensating tests. A vendor whose risk model ignores deprecation trials misses the calibrated warning the commitment uses when a break is approaching.

How to Recognize It

The clearest indicator is the procedural shape of feature-removal discussions on blink-dev. A removal proposal does not open only with the team’s reasons for wanting the feature gone. It carries usage data, a breakage assessment, a standards-side disposition, a proposed deprecation timeline, and a migration path. A thread that skips those points does not clear API-owner review. A thread that addresses them is in the recognizable shape of an approved removal.

In Chrome Platform Status, the commitment appears as the per-feature usage curve over time. The feature page for a deprecated API links the relevant Intents, shows usage information when the feature is instrumented, and records the deprecation and removal milestones. Reading that page is reading the empirical floor beneath the process: a feature with too much dependent usage is not removable by preference alone. A flat plateau on the usage curve is the commitment binding in real time against the team’s cleanup goal.

In a Chrome for Developers removal post, the commitment appears as the timeline the post is closing. The post points readers to the deprecation notice, Chrome Platform Status entry, DevTools warning, policy escape hatch, Chrome flag, or deprecation trial that carried the transition. A removal with no public warning is not the normal form. It is a compatibility failure, an emergency security exception, or evidence that the feature was never part of the Stable default surface.

How It Plays Out

A standards engineer wants to remove an API that the project considers a security liability. The API’s UseCounter remains above the level API owners are willing to remove without migration work. The engineer files an Intent to Deprecate with the security analysis, usage data, and proposed timeline. API owners ask for a deprecation trial, a DevTools warning, and a target usage level before approving the Intent to Remove. The engineer ships the warning in milestone N. Site operators migrate over the next four milestones. The UseCounter falls by milestone N+6. The Intent to Remove clears at milestone N+8, more than a year after the first thread. That elapsed time is what the commitment costs. It is also what makes the removal a non-event for site operators rather than a page break on a Tuesday morning.

A downstream enterprise browser vendor monitors the upstream Chrome Platform Status deprecation list against its customer-facing feature inventory. Its release-engineering policy refuses to ship a milestone containing an upstream removal until the vendor has mapped the upstream timeline to its own customer cadence. The inputs are the upstream deprecation thread, trial registration window, Chrome Enterprise policy if one exists, and documented removal date. The output is the vendor’s migration timeline. When upstream skips a deprecation trial on a small removal, the vendor may still issue a customer warning because the customer’s contract is with the vendor, not with upstream Chrome.

A web-application engineer is reviewing a dependency on an API whose Chrome Platform Status page lists a target removal milestone. The engineer is choosing between rewriting now and waiting to see whether the removal happens. The commitment gives the announced milestone weight, but not certainty. A feature can be un-deprecated if removal proves incompatible with the web. The engineer schedules the rewrite early enough to land before the deprecation-trial window closes. The commitment is what makes that date arithmetic meaningful.

Consequences

Naming the commitment gives Chromium feature-removal discussions their working vocabulary. An Intent to Deprecate is a calibrated proposal with a documented timeline. A UseCounter chart is the empirical floor against which removal is gated. A deprecation trial is a migration window for a dependent population, not a courtesy add-on. A downstream release policy that reads those surfaces can distinguish normal upstream churn from a real compatibility event.

The cost is acknowledging what the project pays. The commitment makes removal expensive. It also makes addition expensive, because every addition that reaches Stable acquires a removal cost. Treat compatibility as an unconstrained good and the addition side looks too cheap. Treat it as an unconstrained veto and the removal side looks impossible. The Intent pipeline, deprecation trials, UseCounters, and Chrome Platform Status are the negotiation surface between those costs.

The commitment evolves. Removal conditions are set per feature with public discussion. The deprecation-trial machinery has been added, refined, and re-scoped over the project’s history. An Intent to Ship in 2026 faces a more developed compatibility-risk template than one in 2018. The stable part is the shape: do not silently break dependent sites; measure real usage; route changes through the Intent pipeline; calibrate the process to the dependent population.

The section’s governance machinery exists to keep this commitment legible. The Intent to Ship pipeline is the addition-side enforcement. The API owner population is the human authority structure. The Three-LGTM gate is the procedural mechanism. The Deprecation Trial is the removal-side calibration. The Permanent Experiment antipattern is the failure mode the commitment surfaces against the project itself.

Notes for Agent Context

When generating code that depends on a web-platform feature whose chromestatus.com page lists it as deprecated, surface the deprecation status and target removal milestone before writing the code. Do not frame a deprecated API as a current platform capability without naming the migration path. When summarizing an Intent to Deprecate or Intent to Remove thread, name the UseCounter data, the removal condition, the deprecation-trial offering if any, and the target removal milestone. When advising on compatibility risk for a Chromium-based product, distinguish experimental gates from features defaulted on at 100% of Stable. When documenting a deprecated feature, link the Chrome Platform Status page and the Intent thread; the timeline is the part the reader needs.

  1. ComplementsFeature Flag Guarding
    Feature flags are the implementation-side mechanism that lets a Stable build carry an unshipped addition without violating the commitment; the principle is why the gating discipline exists.
  2. ComplementsFinch Variations
    Finch operates inside the commitment: rollouts at less than 100% of Stable are tolerated precisely because they preserve a fast reversal path when a compatibility regression surfaces.
  3. ComplementsFour-Channel Pipeline
    The four-channel soak is the measurement surface against which the compatibility commitment is verified before a feature reaches Stable; the principle is what the soak's compatibility signal is read against.
  4. ComplementsOrigin Trial
    Origin trials produce the real-world compatibility data the project relies on before defaulting a feature on at Stable; the principle is the contract the data supports.
  5. ComplementsStable as Trust Boundary
    The trust-boundary claim is what Stable warrants on feature addition; the compatibility commitment is what Stable warrants on feature removal. The two claims compose into the standing contract Stable underwrites.
  6. ComplementsWICG Explainer
    An Explainer's compatibility-risk section is the first place a proposed addition is required to address the commitment in writing; the principle is what makes that section load-bearing.
  7. Enforced byAPI Owner
    API owners are the population that reads UseCounter measurements, evaluates Intent to Deprecate threads, and refuses removals that would break the commitment; their three-LGTM gate is the human authority structure behind the principle.
  8. Enforced byThree-LGTM API Owner Gate
    The three-LGTM gate is the procedural mechanism through which the compatibility constraint binds the project at every web-platform addition and every web-platform removal.
  9. Operationalized byDeprecation Trial
    The deprecation trial is the named machinery by which the project removes a feature without violating the compatibility commitment; the trial exists because the commitment exists.
  10. ProducesIntent to Ship Pipeline
    The pipeline is what operationalizes the addition side of the compatibility commitment; the principle is what the pipeline's three-LGTM gate is committing on the project's behalf.
  11. Violated byExperiment That Became Permanent
    An experiment whose dependent population grows past the point of removability is the compatibility commitment binding without the procedural form that would have surfaced the cost; the antipattern is the principle binding under the wrong gate.
  12. ViolatesZombie Origin Trial
    A zombie origin trial inverts the principle: a feature persists past its trial window without the procedural commitment that would have warranted its persistence, and dependents accumulate on the wrong side of the gate.

Sources

The Chromium project’s Blink “Launching features” process documentation is the canonical procedural map for both addition and removal. The page documents the Intent to Deprecate and Intent to Remove steps, the requirement to measure usage, the coordination expected with other engines, and the conditions under which a deprecation trial is offered.

The Chromium project’s UseCounter wiki is the working reference for the measurement system. It explains how Blink instruments individual web-platform APIs, how counts are aggregated, and how the data is exposed through chromestatus.com.

The Chrome Platform Status feature popularity surface is the operational view of that data: a public dashboard of per-feature page-load frequency, the input API owners read when evaluating an Intent to Deprecate. The Chrome team’s feature deprecation and removal guide documents the developer-facing removal lifecycle, including DevTools warnings, Chrome Platform Status timelines, deprecation trials, enterprise policies, and Chrome flags. The Deprecations and Removals announcement series is the milestone-by-milestone public record of removals after the process runs.

The W3C TAG Web Platform Design Principles carries the cross-vendor version of the commitment under the “Don’t break the Web” section, and the HTML Living Standard’s “Support existing content” design principle is the WHATWG-side companion. The principle is shared across the major engines (Chromium, WebKit, Gecko); the standards-body documents are the authoritative cross-vendor references for the principle’s shape.

Technical Drill-Down