Перейти к основному содержимому

Обновления и стратегии миграции

Цель - предсказуемое, безопасное и контролируемое обновление зависимостей, инструментов и архитектурных решений без регрессий и нарушения UX.

Типы изменений​

Minor updates​

Обновления без breaking changes в публичном API.

MUST​

  • Проходить CI.
  • Не ломать типизацию.

Допускается без отдельного согласования​

Исключение: при наличии security/fatal issues в текущей версии обновление переводится в Major и требует согласования с Техлидом и PM.

Major updates​

Обновления с breaking changes.

MUST​

  • Подготовить план миграции.
  • Согласовать с PM, Техлидом и QA.

FORBIDDEN​

  • Выполнять major update без плана.

Диаграмма: выбор типа обновления​

Изоляция изменений​

MUST​

  • Minor и Major updates выполняются в отдельной ветке.
  • PR содержит только изменения миграции.
  • План rollback определен до начала работ.

FORBIDDEN​

  • Смешивать миграцию с feature-разработкой, UI-фиксами и другими задачами.

Примеры​

✅ Хорошо

  • PR: "Upgrade Next.js 14.2 -> 15.0"
  • Только изменения, связанные с апдейтом

❌ Плохо

  • PR содержит апдейт + новый UI + фиксы

Совместимость и deprecation​

При изменении публичного API обязателен период совместимости.

MUST​

  • Legacy API помечается как deprecated.
  • Период совместимости указан явно.
  • Новый API добавляется до удаления старого.

SHOULD​

  • После периода совместимости legacy API блокируется линтером или на code review.

Пример сценария​

Раньше UI использовал shared слой для server state. Вводится доменный хук, скрывающий детали и обеспечивающий архитектурную границу.

[Пример 1] Шаг 1 - пометка legacy API

// shared/api/legacy-user-query.ts
/**
 * @deprecated
 * Direct usage of infrastructure-level query in UI is forbidden.
 * Use domain-level hook `useUser()` instead.
 *
 * Removal planned after 2 release cycles.
 */
export const useUserQueryLegacy = () => {
  return useQuery(userQueryOptions());
};

[Пример 2] Шаг 2 - добавление актуального API

// entities/user/model/use-user.ts
export const useUser = () => {
  const { data, isLoading, error } = useQuery(userQueryOptions());

  return {
    user: data,
    isLoading,
    error
  };
};

Шаг 3 — период совместимости и миграция

  • legacy API продолжает работать
  • новые изменения используют useUser()
  • старые вызовы постепенно мигрируют
  • после периода — legacy API удаляется

Тестирование и контроль качества​

MUST (перед слиянием major update)​

  • Полный прогон CI на develop-1.
  • Прохождение Critical Path чеклиста.
  • Отсутствие регрессий в:
    • доступности (a11y)
    • локализации (i18n)

Диаграмма: ворота качества​

Процедуры контроля (Code Review)​

Автор PR обязан проверить:​

  • миграция не смешана с feature-разработкой
  • CI прошел полностью, без пропусков шагов
  • понятен план rollback

Ревьюер должен убедиться, что:​

  • изменения изолированы в одном PR
  • нет скрытых breaking изменений
  • тесты и чеклисты выполнены
  • есть план отката