Breaking changes

Launch Process: breaking changes (removing features or changing existing behavior)

  1. Read the guidelines for deprecating a feature.

  2. Measure feature usage in the wild. Various tools are available, but typically this is simply:

  3. Email blink-dev using the "Intent to Remove" template.

    • Respond to any feedback or questions raised in the thread

    • You need at least 3 LGTMs from API owners to remove.

    • API owners will attempt to apply the principles of web compatibility (but you are not required to be familiar with the details here).

    • If you have resolved all feedback and are blocked on API owner LGTMs (or would just like advice in a smaller forum), contact

  4. Notify developers and measure usage.

    • Update the appropriate chromestatus entry, noting the feature as deprecated. Make sure the entry links to suggested alternatives.

    • Notify developers by adding a deprecation console message.

      • Point to the updated chromestatus entry in the console message.

      • Add the API to the big switch in UseCounter::deprecationMessage.

      • Give developers as many milestones as possible to respond to the deprecation.

    • Instrument your code by either:

      • Adding DeprecateAs=[your enum value here] to the feature's IDL definition.* -- See window.performance.webkitGetEntries.

      • Adding a call to UseCounter::countDeprecation somewhere relevant (as we did for the prefixed Content Security Policy headers).

  5. Remove the feature.

If you are unsure of when a feature could be removed, or would like to discourage usage, you may deprecate a feature without a removal deadline. This is strongly discouraged and will require significant justification:

* It takes 12-18 weeks to hit Stable once you enable instrumentation. If there is time pressure you may be able to get permission to merge UseCounter changes into an existing dev/beta branch, and make provisional decisions based on data from beta channel.

Enterprise users have additional difficulties reacting to breaking changes, but we also have additional tools to help them. See shipping changes that are enterprise-friendly for best practices.

Lessons from the first year of deprecations and removals (thread)
  • We should weigh the benefits of removing an API more against the cost it has. Percent of page views by itself is not the only metric we care about.
  • The cost of removing an API is not accurately reflected by the UseCounter for older, widely implemented APIs. It's more likely that there's a longer-tail of legacy content that we're breaking.
  • We shouldn't remove APIs that have small value on the path towards a removal that has significant value. Getting rid of attribute nodes *is* valuable and would benefit the platform. Getting rid of half the attribute node methods is not. So we should evaluate the usage of all the APIs we need to remove together in order to get there. Also, if we remove them, we should remove them all in the same release. Breaking people once is better than breaking them repeatedly in small ways.
  • We should be more hesitant to remove older, widely implemented APIs.
  • For cases where we're particularly concerned about the compatibility hit, we should do the removal behind a flag so that we can easily re-enable the API on stable as we don't know the compat hit until the release has been on stable for a couple weeks.