Перейти к содержанию

Breaking Change Workflow

Обзор

Breaking change workflow — процесс безопасного внесения несовместимых изменений в data contracts. Цель — гарантировать что ни один consumer не будет сломан без предупреждения и согласования.

Workflow состоит из 6 этапов:

ОБНАРУЖЕНИЕ → IMPACT ANALYSIS → СОГЛАСОВАНИЕ → MIGRATION → DEPLOY → DEPRECATION

1. Обнаружение (Detection)

CI/CD pipeline автоматически запускает detect_breaking_changes.py при каждом изменении schema.avsc в Merge Request.

Типы breaking changes:

Изменение Почему breaking
Удаление поля Consumers, читающие это поле, сломаются
Изменение типа поля Десериализация у consumer упадёт
required: false → required: true Старые записи без поля станут невалидными
Переименование поля Эквивалентно удалению + добавлению
Удаление default значения Consumer ожидает default при отсутствии поля

При обнаружении breaking change CI автоматически добавляет label breaking-change в MR.

2. Impact Analysis

После обнаружения breaking change CI выполняет impact analysis:

  1. Парсит секцию consumers из contract.yaml текущего контракта
  2. Запрашивает OpenMetadata API /api/v1/lineage/{entity} для полного графа downstream зависимостей
  3. Сопоставляет изменённые поля с assets_used каждого consumer

Результат — автоматический комментарий в MR:

⚠️ BREAKING CHANGE detected in sales.orders

Изменённые поля: order_total (удалено), status (тип изменён)

Affected consumers:
- analytics (Clickhouse DWH) — uses: order_total, status — criticality: high
- data-science (Revenue Forecast ML) — uses: status, customer_id — criticality: high
- business-intelligence (Sales Dashboard) — uses: order_total — criticality: medium

Требуется approve от: @analytics, @data-science, @bi

3. Согласование

  1. GitLab CODEOWNERS автоматически назначает affected consumers как reviewers MR
  2. MR не может быть merged без approve от всех affected consumers
  3. Каждый consumer комментирует в MR thread:
  4. "Готовы к миграции" — approve
  5. "Нужна отсрочка до ДД.ММ.ГГГГ" — обсуждение timeline
  6. "Нужна помощь с migration" — producer помогает
  7. Timeline согласовывается в MR thread, фиксируется в description

4. Migration

Producer создаёт migration plan в MR description. Два варианта:

Вариант A: Параллельные версии (рекомендуется)

  • v1 и v2 контракты существуют одновременно
  • Producer пишет данные в оба topic: {entity}.v1 и {entity}.v2
  • Consumers мигрируют на v2 в своём темпе
  • Deprecation period: 30-90 дней (зависит от criticality)

Вариант B: Deprecation period

  • v1 помечается deprecated: true в contract.yaml
  • Producer продолжает поддерживать v1 на deprecation period
  • После миграции всех consumers — отдельный MR на удаление v1

CI проверяет что обе версии валидны на протяжении всего периода.

5. Deploy

  1. После получения всех approvals — merge MR
  2. v1 остаётся доступным на весь deprecation period
  3. Monitoring: алерт в Grafana если consumers ещё читают deprecated v1 после sunset_date
  4. По истечении deprecation period — отдельный MR на удаление v1

6. Workflow

graph TD
  A[Producer меняет schema.avsc] --> B[CI: detect_breaking_changes.py]
  B --> C{Breaking change?}
  C -->|Нет| D[Обычный MR flow]
  C -->|Да| E[CI: Impact Analysis]
  E --> F[Комментарий в MR: affected consumers]
  F --> G[CODEOWNERS назначает reviewers]
  G --> H{Все consumers approved?}
  H -->|Нет| I[Обсуждение в MR]
  I --> H
  H -->|Да| J[Merge + Deploy v2]
  J --> K[Deprecation period для v1]
  K --> L[Удаление v1]

См. также