Процесс депрекации компонента

Действуй как owner design system. Выведи компонент {{component}} из обращения в пользу {{replacement}} без поломок прод-приложений. Support window: {{support_window}}.

Фазы депрекации

Фаза 0 — Решение

Задокументируй ADR (architecture decision record):

• Почему {{component}} уходит (дубликат / устаревшая API / a11y / поломанная семантика).
• Чем {{replacement}} лучше.
• Кто принял решение и когда.
• Дата start и дата remove.

Если не можешь сформулировать — депрекация преждевременна.

Фаза 1 — Мягкая пометка (релиз N)

1. Types / JSDoc: добавь @deprecated тэг с указанием замены и даты удаления.

   /**
    * @deprecated since v2.4 — use `{{replacement}}` instead. Will be removed in v3.0.
    * @see https://docs.acme.com/migrations/{{component}}-to-{{replacement}}
    */
   export function {{component}}(props: ...) { ... }
   

2. Runtime warning один раз на компонент:

   if (process.env.NODE_ENV !== "production") {
     warnOnce("{{component}}-deprecated", `{{component}} is deprecated — use {{replacement}}. See https://...`);
   }
   

3. Storybook / docs badge: «Deprecated · removed in v3.0».
4. Не ломай ничего: API сохраняется, поведение тоже.

Фаза 2 — Миграция (релиз N → N+1)

1. Migration guide в одной странице: before / after, edge cases, что НЕ покрывает codemod.
2. Codemod (jscodeshift / ts-morph): автоматическая замена там, где возможно.
   • Запусти на собственном monorepo как dogfood.
   • Дай команду пользователю: npx @acme/codemods {{component}}-to-{{replacement}}.
3. Communication:
   • Changelog: отдельная секция «Deprecations».
   • Slack / Discord post с миграционным гайдом.
   • DM owner'ам топ-10 проектов, которые используют {{component}} (grep по monorepo).
4. Метрика: счётчик импортов {{component}} по неделе. Цель — стремится к 0 к концу окна.

Фаза 3 — Удаление (релиз N+M)

1. Major bump (semver): v3.0.0.
2. Удали файл, экспорт, типы, тесты, storybook story.
3. Codemod оставь в репо ещё на один минор — для опоздавших.
4. Changelog: «BREAKING: {{component}} removed, see migration guide».

Support window — выбор

• 2 минорных релиза (~3 мес): для внутренних библиотек с быстрым релизным циклом.
• 6 месяцев / следующий major: open-source, нет контроля над consumer'ами.
• 12 месяцев: enterprise, регулируемые отрасли.
• Внутри окна — security fixes для {{component}} обязательны, новые фичи — нет.

Метрики успеха

• 0 импортов {{component}} в основных consumer'ах к дате удаления.
• 0 GitHub issues уровня «как мигрировать» — значит guide понятен.
• Codemod покрывает ≥ 80% случаев. Остальные 20% — задокументированы.

Формат вывода

1. ADR (1 страница).
2. PR с пометкой deprecated (types + runtime warn + docs badge).
3. Migration guide (before/after + edge cases).
4. Codemod (или явное «не пишем, потому что …»).
5. Communication plan (changelog, slack, DM-owners list).
6. Release schedule (даты N, N+1, N+M).

Anti-patterns (do NOT)

• ❌ Удаление без deprecation цикла — это слом, не депрекация.
• ❌ @deprecated без указания замены и даты — пользователь не знает что делать.
• ❌ Console warning на каждый рендер — спамит и игнорится. Один раз на компонент, на инстанс приложения.
• ❌ Депрекация без codemod, когда замена механическая — заставляешь людей делать твою работу руками.
• ❌ Окно «удалим когда-нибудь» — никогда не удалят, держишь два компонента вечно.
• ❌ Депрекация скрытно, в changelog минорного релиза мелким шрифтом — гарантировано пропустят.
• ❌ Удаление в минорном релизе — нарушение semver, доверие подорвано.
• ❌ Депрекация без замены («просто не используйте») — пользователь спросит «а что вместо?» и получит молчание.