Retire components with a warning and a removal date

How to do it

Removing a component without notice breaks every screen that uses it. Keep the deprecated component working and listed in the catalogue with its replacement named. Count the remaining uses each week and move them before the date, with a code rewrite script where many uses look alike. Remove it in the next major version. Web APIs retire the same way, as Announce deprecation and sunset in headers shows.

Examples

JavaScript example

// eslint.config.js
export default [{
  rules: {
    'no-restricted-imports': ['error', { paths: [
      { name: '@example/ui', importNames: ['OldDatePicker'], message: 'Deprecated, removed on 2027-03-01. Use DateField.' },
    ] }],
  },
}];

Python example

import datetime
import pathlib
import sys

DEPRECATED = {"OldDatePicker": ("DateField", datetime.date(2027, 3, 1))}

for name, (replacement, removal) in DEPRECATED.items():
    uses = [path for path in pathlib.Path("src").rglob("*.tsx") if name in path.read_text()]
    print(f"{name}: {len(uses)} uses, use {replacement}, removal {removal}")
    if uses and datetime.date.today() > removal:
        sys.exit(f"{name} is past its removal date with {len(uses)} uses left")

How to check

A test file that imports a deprecated component fails lint with a message that names the replacement. A script lists every deprecated component with its use count and removal date. No component with uses left is past its date.

Sources

• Semantic Versioning 2.0.0 FAQ on deprecating functionality

Related rules

• APP-5 Show every component state in a catalogue in Web app interface
• API-29 Announce deprecation and sunset in headers in API design