Deprecation Trial

A reverse origin trial: an existing web-platform feature is disabled for all origins except those that explicitly register for a continued-use window, giving dependent sites a calibrated migration period before the removal reaches every user.

A site operator who deployed an integration against a Chromium web-platform feature five years ago, when the API was unambiguously stable and shipping by default, can find themselves reading a Chrome Platform Status page that announces the feature’s removal in two milestones. The integration isn’t going to migrate itself, and the operator doesn’t have a quarter of engineering budget to spend on it in the next six weeks. The deprecation trial is how the Chromium project gives that operator a runway. The site registers a deprecation-trial token, includes it in HTTP response headers, and the feature keeps working on that origin for the trial’s duration even after the default-on flag has flipped off. The same Origin Trial token machinery that brought the feature into Stable carries it out.

Context

Deprecation Trial sits on the removal side of the Intent to Ship Pipeline, between an Intent to Deprecate (which announces a planned removal and starts a DevTools warning campaign) and an Intent to Remove (which executes the removal). Where a forward Origin Trial gives a feature signed-token access before it ships by default at Stable, a deprecation trial gives a feature signed-token access after the project has decided the default-on shipment will end. The mechanism, the portal, the token format, and the per-origin scoping are identical to the forward trial; what differs is the direction of the default and the population of operators the trial serves.

The pattern operates at the same open-web scale Origin Trials operate at. A typical deprecation-trial registration list includes major-site dependents who built integrations years before the deprecation was announced, third-party libraries whose customers depend on the feature, and downstream Chromium-based product vendors who shipped the feature in their forks. None of these populations can migrate on a Stable-release schedule; the trial buys them an explicit migration window with a hard expiry.

Problem

The Chromium project has decided to remove a feature. The decision survived the Intent to Deprecate three-LGTM gate, the API owner population accepted the security or maintenance rationale, the UseCounter has fallen below the threshold the API owners specified, and the Intent to Remove is calendared for milestone N+8. The dependent population is small in percentage terms but non-trivial in absolute terms: thousands of sites built against the feature when it was stable. Flipping the base::Feature default to DISABLED at milestone N+8 breaks every one of those sites the moment Stable rolls out. The recurring problem is how to retire the feature on the announced schedule without converting the announcement into a Tuesday-morning incident for the surviving dependents.

Forces

• Removal urgency vs. migration cost. The project wants the feature gone (security exposure, maintenance burden, standards-divergence cost); operators want time to migrate their integrations. Neither timeline collapses against the other.
• Hard deadline vs. soft pressure. A migration window with no expiry produces no migration; an expiry that arrives faster than operator engineering bandwidth produces breakage. The pattern needs both a credible deadline and a credible window.
• Per-origin granularity vs. global rollback. A site that needs more time should not block the rollout for every other site that has already migrated; the project should not have to commit to a global extension to accommodate a single operator.
• Procedural cost vs. compatibility cost. Running a deprecation trial costs API owner review attention, blink-dev thread management, portal operations work, and the maintenance burden of keeping the feature alive in source. Skipping the trial costs the project the Web Platform Backward Compatibility commitment that the Chromium project paid years to establish.
• Operator visibility vs. user surprise. A trial registration is public on chromestatus.com and surfaces in DevTools console warnings; that visibility is a feature for operators planning a migration and a liability for sites that prefer their use of the feature not be auditable by competitors.

Solution

The Chromium project gates the continued availability of a removed feature behind a per-origin, time-boxed registration with a cryptographically signed token, structurally identical to the forward Origin Trial mechanism but inverted in default behavior. The sequence:

1. Project files an Intent to Deprecate on blink-dev naming the feature, the rationale, the UseCounter measurement, the announced removal milestone, and the deprecation-trial offering (duration, scope, what the trial token enables). Three API owner LGTMs clear the intent.
2. Project lands a DevTools deprecation warning in milestone N. The warning identifies the feature, the announced removal milestone, the deprecation-trial registration URL, and a migration-path reference. The base::Feature default remains ENABLED at this stage; the warning is the first observable signal to operators that the feature is sunsetting.
3. Site operator visits the Chrome Origin Trials portal, selects the named deprecation trial, registers the origin (scheme + eTLD+1 + port), accepts the trial terms, and receives a signed token bound to that origin with the trial’s expiry date.
4. Site operator deploys the token via the Origin-Trial HTTP response header (or the <meta http-equiv="origin-trial"> form) on documents served from the registered origin.
5. Project flips the base::Feature default to DISABLED at the announced removal milestone N+K. From that milestone forward, the feature is off by default for every user; only requests from documents that carry a valid deprecation-trial token re-enable it on a per-document basis.
6. At trial end the Chrome team disables the trial server-side. Tokens stop verifying; the feature falls back to the DISABLED default everywhere. The implementation is then removed from the source tree in a follow-up Intent to Remove milestone.

What makes the pattern work is the asymmetry between the cost of keeping a feature alive for a small registered population and the cost of carrying it for every user. The project pays implementation maintenance for the trial’s duration; dependent operators carry the migration work on their own schedule inside the trial window; users who never depended on the feature in the first place are unaffected. The hard expiry inside the token is what converts an open-ended deprecation into a measurable migration.

How It Plays Out

A web-platform engineer drives the removal of SharedArrayBuffer-without-cross-origin-isolation, a feature deprecated in 2021 after Spectre forced the cross-origin-isolation requirement. The Intent to Deprecate clears with a one-year deprecation-trial offering: any origin that registers gets continued access to non-isolated SharedArrayBuffer for the trial window while it implements the COOP/COEP headers the isolated form requires. Three thousand origins register; the major-site customers of two analytics vendors register on the vendors’ behalf; the DevTools warning surfaces in every Chrome installation for the full trial window. At the trial’s announced end, the base::Feature default flips. The remaining dependent sites are the population that did not migrate and did not register; the project has the public record of the trial’s announcement, the registration window, and the warning campaign to point to when those operators discover the removal. The total elapsed time from the original CVE that motivated the deprecation to the final removal is more than four years.

A second team at a downstream Chromium-based browser vendor faces a deprecation upstream. An API their product depends on has entered an upstream deprecation trial; the trial expires before the vendor’s planned milestone. The vendor’s options are to register the upstream trial and patch their fork to consume the token (a tractable engineering project), migrate their integration to the upstream-recommended replacement (a larger project, depending on what the integration does), or carry a downstream patch reverting the upstream base::Feature default flip (the heaviest option, requiring ongoing rebase work against every upstream change to the feature’s implementation). The vendor picks the registration path for the first six months of the trial, migrates during that window, and lets the registration expire on schedule. The trial mechanism made the vendor’s planning calendar deterministic; the absence of the trial would have forced the third option.

A third scenario shows the pattern’s relationship to the Experiment That Became Permanent antipattern. A new API owner running an annual stalled-trial audit finds a feature that was launched as a forward Origin Trial four years ago, has been extended five times, and has accumulated a major-site dependent population. The original feature owner has rotated off; the successor inherited the open review items but didn’t drive them to a terminal state. The audit forces a decision: Intent to Ship the feature on the strength of its current dependent population, or convert the stalled trial into a Deprecation Trial and remove the feature on a defined schedule. The owner picks the deprecation path; the dependent sites receive eighteen months’ notice; two of the major-site dependents negotiate custom continued-use arrangements through the trial registration; the rest migrate. The forward trial that became permanent is converted, by way of the deprecation trial, back into a governed terminal state.

Consequences

Benefits. The Intent to Remove gate arrives with a documented migration window, a public registration list, an operator-side commitment record, and a hard expiry date. API owners read that record when granting the third LGTM. Dependent operators receive a structured migration path on a calendar they can plan against; the Chromium project receives a removal that does not break the Web Platform Backward Compatibility commitment. The DevTools warning surface provides per-page visibility to operators who hadn’t tracked the deprecation in blink-dev; the trial portal provides a single registration surface for every dependent origin. The same machinery that brought the feature into Stable through a forward Origin Trial carries it out, which means the trial code path is well-exercised and the operator experience is the one most teams already know.

Liabilities. Deprecation trials are slow and expensive. The maintenance burden of a feature in deprecation extends across the announcement window, the trial duration, and any extension period — typically two to three years from Intent to Deprecate to final source-tree removal. The implementation must continue to receive security review, platform-update accommodation, and architectural-change adaptation work for the trial’s duration even after the project has decided the feature has no long-term future. A second liability is the registration-and-extension dynamic: a trial that accumulates a politically important enrollment list (major-site dependents whose continued operation matters more to the Chrome team than the removal’s stated rationale) can be pressured into successive extensions, recreating the dynamic the Experiment That Became Permanent antipattern names on the addition side. The trial’s defining property is its expiry; an extension that arrives without a new and credible removal date converts the trial into an indefinite preservation of the feature.

The pattern doesn’t guarantee a clean removal. It guarantees that the removal operates over a public migration record rather than a Tuesday-morning incident. A feature whose deprecation trial closes with dependents still on the feature reaches the same end state as one with no trial at all; what differs is the project’s standing to point at the announcement, the warning campaign, and the registration window when those dependents file the incident reports.

Notes for Agent Context

When an AI coding agent is asked to add or maintain code that depends on a Chromium web-platform feature whose chromestatus.com page lists it in a deprecation trial, the agent must surface the trial’s expiry date, the announced final-removal milestone, and the recommended replacement API in the change description before writing any code that consumes the feature. The agent must not generate documentation that describes a deprecation-trial-gated feature as a stable platform capability; the trial token is a finite-duration permission to keep using a sunsetting feature, not a substitute for migration. When asked to deploy a deprecation-trial token, wire the registration through the per-origin token path (HTTP response header or <meta> element on documents served from the registered origin), confirm the token is bound to the exact origin the document is served from (eTLD+1 plus scheme plus port), and refuse to mark the integration complete without a planned migration date that precedes the trial’s expiry. When advising on whether to register a deprecation trial, name the cost of the alternative (immediate breakage at the removal milestone) and the cost of registration (an explicit deadline against which migration engineering must be scheduled); do not collapse the decision into a default recommendation in either direction.

Related Patterns

Sources

The deprecation-trial mechanism is documented inside the broader Origin Trials framework on developer.chrome.com; the mechanism’s design rationale was published as part of the Origin Trials’ founding documents in 2017 and refined over the project’s history to support reverse-direction trials. The chromestatus.com per-feature page is the source of truth for any active deprecation trial’s lifecycle, including registration counts and announced expiry. The blink-dev archive carries every Intent to Deprecate and Intent to Remove thread that has gated a trial in either direction. The Chromium project’s Deprecations and Removals announcement series on the Chrome developer blog is the public surface where each deprecation-trial offering is announced and where operators learn the registration URL and the migration recommendation. The Privacy Sandbox program’s third-party cookie deprecation is the canonical large-scale instance of the pattern’s mechanism interacting with a dependent population whose collapse the project could not unilaterally absorb; the 2024 announcement that the cookie decision would route through a user-facing browser prompt rather than a unilateral disablement is the project’s explicit acknowledgment that the pattern’s hard-expiry property does not hold when the dependent population is “an industry.”

Technical Drill-Down

• Origin Trials documentation, deprecation-trial section — the canonical reference for the reverse-trial mechanism, including the registration surface, token deployment, and the relationship between trial expiry and the underlying base::Feature default.
• Origin Trials portal — the registration interface; active deprecation trials are listed alongside forward trials with their expiry milestones.
• Chrome Platform Status — the per-feature operational view; deprecated features carry a Deprecated status with announced removal milestones and deprecation-trial enrollment data when a trial is offered.
• Deprecations and Removals announcement series — the public announcement surface; each deprecation-trial offering is announced here with the registration URL and the migration recommendation.
• blink-dev archive — the primary record for Intent to Deprecate and Intent to Remove threads, including the deprecation-trial offerings the three-LGTM gate has approved.
• Chromium project documentation on feature launches — the procedural states a feature passes through, including the removal arm of the pipeline the deprecation trial occupies.