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

Требования к миграциям

Обновления и миграции требуют отдельного планирования и контроля. Изменения стека, зависимостей или API должны быть предсказуемыми, безопасными и допускать откат. Один PR — одна цель: чем меньше PR, тем проще откат.

Типы обновлений​

Minor updates​

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

MUST​

  • CI пройден полностью — линтинг, сборка, тесты (если применимо).
  • Типизация не ломается — нет TS-ошибок после обновления.
  • Поведение API сохраняется — нет изменений в публичных интерфейсах.

Что входит в Minor​

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

Minor-обновления мержатся после прохождения CI и review любого члена команды.

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

Major updates​

Любые изменения с breaking changes или значительным влиянием на кодовую базу.

MUST​

  • Подготовить план миграции — до начала работ.
  • Согласовать с PM, Tech Lead и QA — до начала работ.
  • Период тестирования — полный прогон CI, проверка rollback, QA затронутых областей.
  • Возможность отката — определена и задокументирована.

Что входит в Major​

  • Обновление ключевых зависимостей:
    • React (например: 18 → 19)
    • Node.js (например: 18 → 20)
    • Next.js (например: 14 → 15)
    • UI-библиотеки (Material UI, Ant Design и т.д.)
  • Миграция инфраструктуры:
    • Webpack → Vite
    • CRA → Next.js
  • Редизайн внутренних API — изменение публичных интерфейсов проекта

FORBIDDEN​

  • Major update без плана миграции.
  • Major update без согласования с PM, Tech Lead, QA до начала работ.
  • Major update без периода тестирования.
  • Миграция без возможности отката.

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

MUST​

  • Обновления выполняются в отдельной ветке — изолированно от feature-разработки.
  • PR содержит только изменения миграции — никаких фиксов, UI-правок, feature-работы.
  • План rollback определён до начала работ — способ отката задокументирован в описании PR.

Способы отката​

СпособКогда применяется
Revert PRИзолированные изменения, нет зависимостей
Feature flagВыключение флага возвращает предыдущее поведение
Переключение import-точкиМиграция внутренних API

FORBIDDEN​

  • Смешивать миграцию с feature-разработкой, UI-фиксами и другими задачами.
// ❌ Плохо: PR содержит и апдейт, и новую фичу
// PR: "Upgrade Next.js 15 + Add user profile page"

// ✅ Хорошо: PR только про апдейт
// PR: "Upgrade Next.js 14.2 → 15.0"
// Только изменения, связанные с обновлением

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

MUST (для major updates)​

  • Полный прогон CI — без пропусков шагов.
  • Проверка rollback-сценария на staging — убедиться что откат работает.
  • QA проводит тестирование затронутых областей:
    • При глобальных изменениях — полная регрессия.

SHOULD​

  • Запуск E2E тестов (если применимо).
  • Отсутствие регрессий в доступности (a11y) и локализации (i18n).

Code Freeze​

MUST​

Крупные миграции требуют code freeze затронутых областей:

  • Остановка feature-разработки в затронутых модулях
  • Ограничение изменений в основной ветке

Согласование​

Code freeze согласовывается с PM и обсуждается с командой заранее.

Deprecation — трёхшаговый процесс​

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

MUST​

Изменение публичного API выполняется в 3 шага:

Шаг 1 — Пометка Legacy API как @deprecated​

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

Обязательно указать:

  • Причину deprecation
  • Альтернативу (что использовать вместо)
  • Срок поддержки

Шаг 2 — Добавление нового API​

Новая реализация покрывает все сценарии старого API.

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

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

Шаг 3 — Период совместимости​

  • Legacy API продолжает работать — нет breaking changes сразу.
  • Новый код обязан использовать новый API — через линтер или code review.
  • Существующие вызовы мигрируются постепенно — не всё сразу.
  • По завершению миграции — legacy код удаляется.

SHOULD​

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

// .eslintrc.js
rules: {
  'no-restricted-imports': ['error', {
    patterns: [{
      group: ['**/legacy-user-query'],
      message: 'Use useUser() from entities/user instead'
    }]
  }]
}

Миграционные скрипты​

SHOULD​

  • Официальные codemods для фреймворков / библиотек:
    • React: npx react-codemod
    • Next.js: npx @next/codemod
    • Material UI: npx @mui/codemod
  • Кастомные скрипты миграции для внутренних API — через jscodeshift или ts-morph.
# Пример: миграция с Pages Router на App Router в Next.js
npx @next/codemod@latest app-router-recipe .