Жизненный цикл контрактов
Каждый контракт данных проходит через определённые этапы жизненного цикла — от создания до вывода из эксплуатации.
Этапы жизненного цикла
graph LR
A[Черновик] --> B[Рецензия]
B --> C[Активный]
C --> D[Устаревший]
D --> E[Отключен]
style A fill:#9E9E9E
style B fill:#FF9800
style C fill:#4CAF50
style D fill:#FFC107
style E fill:#F44336
| Этап | Описание | Допустимые операции |
| Черновик | Начальное создание, ещё не утверждено | Свободное редактирование |
| Рецензия | На проверке governance | Комментарии, запросы изменений |
| Активный | Готов к production, потребители могут полагаться | Только через bump версии |
| Устаревший | Запланирован к удалению, требуется миграция | Только для чтения, нет новых потребителей |
| Отключен | Удалён из production | Только архив |
Управление версиями (SemVer)
Контракты следуют Semantic Versioning:
| Компонент | Когда увеличивать | Примеры |
| MAJOR (X.0.0) | Ломающие изменения | Удаление поля, изменение типа, удаление enum-значения |
| MINOR (0.X.0) | Обратно совместимые | Добавление nullable-поля, добавление enum-значения |
| PATCH (0.0.X) | Только документация | Исправление описания, обновление контакта |
Обнаружение breaking changes
CI-пайплайн (ci/detect_breaking_changes.py) автоматически обнаруживает:
- Удаление поля
- Изменение типа поля
- Удаление enum-значения
- Изменение nullable → not null
- Ужесточение ограничений
# Проверка текущей версии и предложение следующей
python contracts/ci/suggest_version.py contracts/domains/sales/orders/
# Валидация bump версии
python contracts/ci/check_version_bump.py contracts/domains/sales/orders/
Правила эволюции схемы
| Тип изменения | Допустимо? | Процесс |
| Добавить nullable-поле | Да | MINOR |
| Добавить поле с default | Да | MINOR |
| Удалить optional-поле | Нет | MAJOR + deprecation |
| Удалить required-поле | Нет | MAJOR + deprecation |
| Изменить тип поля | Нет | MAJOR + deprecation |
| Добавить enum-значение | Да | MINOR |
| Удалить enum-значение | Нет | MAJOR + deprecation |
| Переименовать поле | Нет | Добавить новое + deprecate старое |
Политика deprecation
График
| Фаза | Длительность | Действия |
| Объявление | День 0 | Отметить контракт, уведомить потребителей |
| Период миграции | Минимум 90 дней | Поддерживать старую и новую версии |
| Предупреждение | 30 дней до отключения | Ежедневные алерты оставшимся потребителям |
| Отключение | Конец периода | Удалить устаревший контракт |
Поля deprecation в контракте
deprecation:
deprecated: true
deprecated_at: "2026-01-15"
sunset_date: "2026-04-15" # Минимум 90 дней
successor: "sales/orders-v2" # Контракт-замена
migration_guide: "./MIGRATION.md"
remaining_consumers:
- name: "Legacy Dashboard"
team: "bi-team"
target_migration_date: "2026-03-01"
status: "in_progress"
Дополнительные материалы