What problem does this address?

In the past, there has been a lot of ambiguity in our back compat policy. We've been working to bring more clarity around these issues, through efforts like Private APIs and removing __experimental prefixes (#59418).

Here, I'd like to increase clarity around component deprecations. The goal of this is twofold:

• Minimize uncertainty and disruption for extenders, by setting clearer expectations.
• Simplify the decision-making process for maintainers, by having unambiguous guidelines.

What is your proposed solution?

A "deprecation", at the very basic level, means that we don't encourage new usages of the component.

There are two reasons we may feel this way:

• Reduce maintenance cost. Some components are not used enough to justify their continued maintenance. In general, anything that is marked as deprecated will no longer receive enhancements or bug fixes.
• Encourage use of a better alternative. There may be a new, improved version in the component library. Or, it's now easier to use standard HTML elements and CSS, rather than a component that abstracted or polyfilled it.

If there is no big harm in keeping existing usages, we will be as unobtrusive as possible about the deprecation ("passive deprecation"). On the other hand, if there are strong enough reasons to discourage continued usage, we will also log a deprecation warning in the console and write a Dev Note ("soft deprecation"). Additionally, if the bundle size or maintenance cost justifies the eventual removal of the code, the deprecation warning will include an end version ("hard deprecation").

If circumstances change, a component may later progress into a stronger level of deprecation.

Deprecation levels

Passive deprecation

• Mark with TypeScript @deprecate
• Update docs (readme, JSDoc, Storybook)

Soft deprecation

• Mark with TypeScript @deprecate
• Update docs (readme, JSDoc, Storybook)
• Dev note
• deprecated() warning with no end version

Hard deprecation

• Mark with TypeScript @deprecate
• Update docs (readme, JSDoc, Storybook)
• Dev note
• deprecated() warning with end version
• Delete from package when end version arrives

flowchart TD
  1{{"`Do we encourage _new_ usages of this component?`"}}
  1 -- Yes --> 2[Yay!]
  1 -- No --> 3{{"`Are there strong reasons to discontinue _existing_ usage?`"}}
  3 -- Yes --> 4{{"`Is the bundle size or maintenance cost big enough to justify completely deleting the component?`"}}
  3 -- No --> pdep
  4 -- Yes --> hdep
  4 -- No --> sdep

  subgraph pdep ["Passive Deprecation"]
    pdep1[TypeScript @deprecate]
    -.- pdep2[Update docs]
  end

  subgraph sdep ["Soft Deprecation"]
    sdep1[TypeScript @deprecate]
    -.- sdep2[Update docs]
    -.- sdep3[Dev note]
    -.- sdep4["deprecated() with no end version"]
  end

  subgraph hdep ["Hard Deprecation"]
    hdep1[TypeScript @deprecate]
    -.- hdep2[Update docs]
    -.- hdep3[Dev note]
    -.- hdep4["deprecated() with end version"]
    -.- hdep5[Delete from package when end version arrives]
  end