How Chromium Deprecates and Removes Legacy Web Features

This article provides a complete overview of how the Chromium project safely phases out outdated web platform features without breaking the web. By relying on anonymous telemetry published on Chrome Status, Chromium engineers monitor the real-world adoption of legacy APIs until usage drops below a microscopic threshold. Once this data proves a feature is rarely used, the team executes a structured "Intent to Deprecate and Remove" process, utilizing developer warnings, staged rollouts, and kill switches to permanently delete the code while maintaining browser stability and security.

Tracking Usage with Chrome Status

Before Chromium engineers can remove a legacy feature from the Blink rendering engine, they must prove that doing so will not disrupt users.

  1. UseCounters: Engineers instrument the feature's code with a UseCounter. This metric tracks how frequently the feature is triggered across all page loads by Chrome users who have opted into sharing anonymous usage statistics.
  2. Chrome Status: This telemetry data is made publicly available on the Chrome Status dashboard, allowing anyone to see the percentage of page views that rely on a specific API.
  3. The Threshold: While there is no single hardcoded number for every situation, Chromium generally looks for usage to drop below a tiny threshold—typically between 0.03% and 0.001% of all page loads. Features with severe security risks may be removed at slightly higher thresholds, while features that cause complete page failures require much lower numbers.

Once a feature's usage on Chrome Status falls below the acceptable threshold, engineers cannot simply delete the code. They must follow the public Blink launch process.

  • Intent to Deprecate and Remove: The engineer sends a formal proposal to the public blink-dev mailing list. This document outlines why the feature is being removed (such as security vulnerabilities, poor standardization, or the availability of better modern alternatives), presents the low usage data from Chrome Status, and provides a timeline.
  • HTTP Archive Analysis: If usage is near the upper limit of the threshold, engineers query the HTTP Archive to inspect the actual websites still using the feature. This helps determine if the usage comes from broken legacy scripts, bots, or critical functionality on major websites.
  • API Owner Approval: To proceed, the proposal must receive three "LGTMs" (Looks Good To Me) from the Blink API Owners—a group of senior engineers responsible for overseeing the health and compatibility of the web platform.

The Deprecation Phase

Approval leads to the deprecation phase, which is designed to drive the remaining usage down to zero by alerting web developers.

  • DevTools Warnings: Chromium updates the browser to emit warnings in the DevTools Console whenever the deprecated feature is used, instructing developers on what modern API to use instead.
  • The Issues Tab and Reporting API: Beyond simple console logs, Chromium surfaces structured warnings in the DevTools "Issues" tab. It also triggers the Reporting API, which allows website owners to automatically receive telemetry reports when their live users encounter a deprecated feature on their site.
  • Outreach: If the HTTP Archive analysis reveals that a specific popular third-party library or major website is responsible for most of the remaining usage, the Chromium team often reaches out directly to those maintainers to help them migrate.

Removal and Rollback Safety

After a grace period—usually spanning several browser milestones—the feature is ready to be turned off, provided usage has remained beneath the target threshold.

  1. Disabling by Default: Instead of immediately deleting the code, engineers flip the feature's internal flag to "disabled" in the source code.
  2. Finch Kill Switch: Chromium uses a server-side configuration system called Finch. If disabling the feature causes unexpected breakage in the real world (especially on internal corporate networks that do not report public telemetry), engineers can use Finch to remotely re-enable the feature for all users without requiring a browser update.
  3. Enterprise Policies: Because businesses often rely on legacy web applications that are expensive to update, Chromium frequently provides an enterprise policy. This allows IT administrators to temporarily re-enable the removed feature for their organization, giving them several extra months to update their internal tools.
  4. Code Deletion: Once the feature has been disabled in the stable channel for a few releases with no major bug reports, and any temporary enterprise policies have expired, engineers finally delete the underlying C++ code from the Chromium repository.