Migration Playbook¶
Обзор¶
Руководство по миграции data contracts: backward-compatible изменения (MINOR) и breaking changes (MAJOR).
Backward-compatible changes (MINOR)¶
Эти изменения не требуют согласования с consumers:
| Изменение | Действие | Версия |
|---|---|---|
| Добавление nullable поля | Добавить в schema.avsc с "default": null | MINOR |
| Добавление default значения | Consumers не затронуты | MINOR |
| Поле стало optional | Consumers не затронуты | MINOR |
Процесс: обычный MR → MINOR version bump → не требует consumer approval.
Breaking changes (MAJOR)¶
Вариант A: Параллельные версии (рекомендуется)¶
Шаг 1: Создать v2 контракт (contracts/domains/sales/orders-v2/)
Шаг 2: Producer пишет данные в оба topic: sales.orders.v1 + sales.orders.v2
Шаг 3: Consumers мигрируют на v2 в своём темпе
Шаг 4: Deprecation period (30-90 дней)
Шаг 5: Monitoring: алерт если consumers ещё на v1
Шаг 6: После migration всех consumers — удалить v1
Вариант B: In-place migration (для простых случаев)¶
Шаг 1: Добавить новое поле параллельно старому
Шаг 2: Producer заполняет оба поля
Шаг 3: Consumers переключаются на новое поле
Шаг 4: Удалить старое поле (это отдельный MAJOR change)
Database migration considerations¶
Database migrations — один из самых опасных источников breaking changes:
| Операция | Breaking? | Комментарий |
|---|---|---|
| Rename column | Да | Даже если "просто переименование" |
| Change column type | Да | Всегда breaking |
| Add NOT NULL constraint | Да | Может сломать writer'ов |
| Add nullable column | Нет | Безопасно |
| Add index | Нет | Безопасно |
Рекомендация: CI hook который проверяет database migration файлы на breaking changes.
Rollback plan¶
Каждый MAJOR change должен иметь rollback plan в MR description:
- Восстановить v1 контракт + topic
- Данные в raw tier не теряются (immutable storage)
- Consumers переключаются обратно на v1
Avro Schema Evolution Rules¶
| Изменение | Совместимо? |
|---|---|
| Добавление nullable поля с default | Да (BACKWARD) |
| Добавление поля без default | Нет (FORWARD only) |
| Удаление поля с default | Да (FORWARD) |
| Удаление поля без default | Нет |
| Изменение типа поля | Нет |
| Переименование поля | Нет (aliases можно использовать) |
Ссылка: Avro Schema Resolution
Deprecation в contract.yaml¶
При deprecation обновите секцию в contract.yaml:
deprecation:
deprecated: true
deprecated_at: "2026-01-31"
sunset_date: "2026-04-30"
successor: "sales/orders-v2"
migration_guide: "./MIGRATION.md"
См. также¶
- Breaking Change Workflow — полный процесс breaking changes
- Contract Versioning Workflow — версионирование контрактов
- Коммуникация Producer-Consumer — согласование с consumers