Модуль 8.3. Управление изменениями и версиями требований
Темы: change control board, версионирование, диффы, миграции. Артефакт: журнал изменений. Практика: оформить change request.
Системный аналитик (SA) отвечает за то, чтобы изменения были управляемыми, обратимыми и прослеживаемыми. В этом модуле вы получите рабочую схему: от инициирования запроса на изменение (CR) до релиза с миграциями и обратной совместимостью, с чёткими артефактами — журналом изменений, диффами спецификаций и планом миграций.
Базовые понятия и роли (как сотруднику — к исполнению)
Что считаем «изменением»
- Требования: SRS/BRD/NFR, модели (ER/BPMN/UML), словарь домена.
- Контракты: OpenAPI/AsyncAPI/Avro/JSON Schema, правила (DMN), SQL-схемы.
- Процессы: фичефлаги/конфиги, политики безопасности/данных.
- Документация: AC/BDD, RTM, «живые» .feature.
CCB — Change Control Board
Состав: PO/PM, SA, QA Lead, Tech Lead/Architect, SRE/DevOps, при необходимости — Data/Legal/Security.
Задачи: приоритизация и принятие решений по CR: approve / approve with conditions / defer / reject.
Календарь: еженедельно (оперативные CR) + ad-hoc для срочных.
RACI (фрагмент)
- Подготовка CR и анализ влияния: R (SA), C (Tech Lead, QA), I (PO)
- Решение CCB: A (PO/PM), R (все)
- Миграция/релиз: R (Dev/SRE), C (SA), I (бизнес, саппорт)
Версионирование: требования и контракты
Принципы
- Docs-as-Code: храним SRS/диаграммы/контракты в Git (Markdown, PlantUML/Mermaid, BPMN XML, OpenAPI YAML).
- Semantic Versioning (semver): MAJOR.MINOR.PATCH для API/событий/схем.
- Версионирование требований: по релизам — релизные теги (reqs-vX.Y) и сквозная нумерация требований (REQ-1234).
- Окна поддержки: таблица LTS/поддерживаемых версий и план деактивации.
Решаем, какой bump нужен (решётка решения)
|
Изменение |
Клиенты ломаются? |
Версия |
|---|---|---|
|
Добавили необязательное поле в ответ/событие |
нет |
MINOR |
|
Добавили обязательное поле во вход |
да |
MAJOR |
|
Изменили описание/тексты без контракта |
нет |
PATCH |
|
Исправили ошибку схемы без изменения структуры |
нет |
PATCH |
|
Переименовали поле/тип |
да |
MAJOR |
|
Добавили новый endpoint/топик |
нет |
MINOR |
Ветвление/PR-поток
- main (релизная ветка), release/x.y, feature/CR-<id>-short-name.
- Любое изменение требований идёт через PR с: диффами, ссылками на RTM, обновлёнными AC/BDD, планом миграций и release notes.
Диффы: как показывать различия правильно
Текст и модели
- Markdown/Doc: обычный Git-дифф.
- UML/BPMN/ER: хранить как код (PlantUML/Mermaid, BPMN XML) → диффится строково.
- DMN: табличный CSV/Excel + экспорт в XML (в репозитории — обе версии).
Контракты
-
OpenAPI/AsyncAPI: дифф-отчёт «breaking/non-breaking» (артефакт PR).
Пример (фрагмент YAML до/после — добавили необязательное поле promoCode):
# before
components:
schemas:
PaymentRequest:
type: object
required: [orderId, amount, currency]
properties:
orderId: { type: string, format: uuid }
amount: { type: number, format: decimal }
currency:{ type: string, example: RUB }
# after
components:
schemas:
PaymentRequest:
type: object
required: [orderId, amount, currency] # не меняли
properties:
orderId: { type: string, format: uuid }
amount: { type: number, format: decimal }
currency: { type: string, example: RUB }
promoCode: { type: string, minLength: 3 } # добавлено (non-breaking)
- Avro/JSON Schema: отмечаем эволюцию (добавили поле с default: совместимо для потребителей).
База данных (SQL)
-
Храним миграции (expand/contract) и ER-модель. Дифф — в PR.
Пример expand-шаг:
-- V2025_08_20_01__add_promo_code.sql ALTER TABLE payment ADD COLUMN promo_code VARCHAR(32); -- backfill по правилам, индексы при необходимости contract-шаг (после переключения и стабилизации): -- V2025_09_10_02__drop_legacy_column.sql ALTER TABLE payment DROP COLUMN old_discount_code;
Процесс управления изменениями (workflow)
Жизненный цикл CR
Draft → Submitted → Triage (анализ влияния) → CCB Decision → In Progress → Ready for Release → Released → Closed
Что содержит CR (шаблон)
CR ID: CR-2025-081 Название: Добавить promoCode в Payment API (необязательный) Инициатор/заказчик: Маркетинг (кампания X) Описание: Клиент может указать промокод при оплате; валидируем по каталогу. Основание: рост конверсии, измерение влияния Область: OpenAPI /payments, фронт (поле), БД (payment.promo_code), события payment.authorized.v1 Тип изменения: non-breaking (MINOR) Анализ влияния: Требования/AC: SRS §3.2 обновить; AC-1..AC-3 → AC-1', AC-4 (валидация) Контракты: OpenAPI v1.3→v1.4 (MINOR); событие без изменений Данные: колонка promo_code + backfill null Безопасность/Приватность: нет PII, маска не требуется Наблюдаемость: добавить label promo_code? (нет, только бизнес-метрики агрегированные) Совместимость: клиенты старой версии не ломаются Оценка/план: Версия: API 1.3 → 1.4 Миграции: expand (добавить колонку) → релиз → опциональный backfill → contract позже (если будет) Фичефлаг: ui.promo.enabled Риск: низкий; откат: просто скрыть флаг, не катить схему назад Коммуникация: Release notes: да; дата GA: 2025-09-05; Deprecation: не требуется Приложения: дифф OpenAPI, SQL миграция, макеты формы, обновлённые AC/BDD, RTM
Triage и CCB: критерии принятия
- Изменение вписано в стратегию/OKR; есть измеримая ценность.
- Влияние на совместимость и комплаенс — прозрачно.
- Есть план миграций/отката, оценка рисков, владельцы.
- Обновлены AC/BDD/RTM, артефакты наблюдаемости и документации.
Анализ влияния (impact analysis)
Матрица влияния
|
Объект |
Что меняется |
Риск |
Меры |
|---|---|---|---|
|
Требования/AC |
SRS §, AC-новые |
Низк/ср/выс |
Ревью, трассировка RTM |
|
API/Events |
схема/версия/сигнатуры |
Совместимость |
semver, deprecated-план, контракт-тесты |
|
БД |
таблицы/индексы/данные |
Производительность/данные |
expand/contract, backfill, индексы |
|
UI/UX |
поля/тексты/валидация |
Конверсия |
A/B, feature flag |
|
Безопасность |
доступы/данные |
Комплаенс |
DPIA/политики |
|
DWH/BI |
витрины/семантика |
Ошибки отчётов |
SLA данных, тесты витрин |
|
Наблюдаемость |
метрики/логи/трейсы |
Диагностика |
RED/USE обновить, алерты |
RTM (трассировка)
Обновляем связь REQ → AC → UC/диагр. → API/события → тесты (.feature) → метрики. Любой CR обязан обновить RTM-строки.
Миграции: стратегии и примеры
БД: expand/contract (blue-green)
- Expand: добавить новые объекты (колонки/индексы), обеспечить совместимость кода со старым и новым.
- Switch: код начинает использовать новое поле/структуру.
- Contract: удалить legacy после стабилизации/мониторинга.
API: двойная публикация и фичефлаги
- Добавляйте новое поведение под фичефлаг (kill-switch).
- Параллельные версии /v1/... и /v2/... (для MAJOR).
- Deprecation policy (пример): анонс ≥30 дней → dual-run ≥60 дней → отключение → архив.
События/шина (совместная эволюция)
- Additive-only + default → назад совместимо.
- Схема v1 и v2 с совместимым ключом партиционирования; консьюмеры постепенно переходят.
- Schema Registry: запрещаем breaking без MAJOR.
Backfill и «write-through»
- Если новое поле вычисляется из старых, запускаем backfill (batch) + write-through (онлайн запись).
- В отчётности — помечаем окна неполноты.
Откат (rollback)
- Идеально — roll-forward (фикс в новой версии).
- Если нельзя — откат фичефлага/конфига; контракт не откатываем без MAJOR (иначе клиенты ломаются).
Документация и «живые» артефакты
Журнал изменений (Change Log) — артефакт
Храним в репозитории (CHANGELOG.md), формат по релизам:
# Changelog — Payments API ## [1.4.0] — 2025-09-05 ### Added - `promoCode` (optional) в `PaymentRequest`. Non-breaking. CR-2025-081. ### Changed - Тексты ошибок валидации (RU/EN) — без изменения кода ошибок. ### Deprecated - Нет. ### Migration - SQL: V2025_08_20_01__add_promo_code.sql (expand). Backfill не требуется. ### Docs/Contracts - OpenAPI v1.4.0, SRS v3.7, .feature обновлены. ## [1.3.2] — 2025-08-12 ### Fixed - Исправлен пример JSON в документации (PATCH).
Release notes (для внешних клиентов)
Коротко «что изменилось», «что делать клиентам», «сроки устаревания», ссылки на контракты/гайды.
Пример: от CR до релиза (сквозной кейс)
Запрос: маркетинг просит промокоды в оплате.
- CR оформлен (см. шаблон) → Triage: влияние на API/БД/UI, non-breaking → MINOR.
- CCB: approve; условия — флаг ui.promo.enabled, A/B, метрика конверсии.
-
Реализация:
- SRS/AC/BDD обновлены; OpenAPI 1.4; SQL expand; UI поле.
- Контракт-тесты подтверждают, что старые клиенты работают.
- Релиз: включили флаг 10% трафика; наблюдаем error-rate/latency/конверсию; через 1 неделю — 100%.
- Документация: CHANGELOG, release notes, RTM.
- Закрытие CR: критерии выполнены, журнал обновлён.
Риски и анти-паттерны (и как их гасить)
|
Риск |
Симптом |
Что делать |
|---|---|---|
|
«Тихие» изменения без версий |
Клиенты ломаются |
Semver, CCB, запрет на деплой контрактов без тега |
|
Переименование поля «в лоб» |
Миграция больная |
Паттерн expand/contract, alias-поле, двойная публикация |
|
Нет журнала изменений |
Саппорт тонет |
CHANGELOG.md, release notes по шаблону |
|
Миграция данных «биг-бэнг» |
Долгие простои |
Инкрементальные backfill, write-through |
|
Diff только по текстам |
Упустили контракт |
Делаем специализированные дифф-артефакты (API/ER/DMN) |
|
Нет плана отката |
Паника при инциденте |
Фичефлаги/конфиги, roll-forward стратегия |
|
Забыли DWH/отчёты |
Битые витрины |
Включать DWH/BI в impact analysis и миграции |
|
Нет RTM-обновления |
Потеря прослеживаемости |
Блокирующее правило CCB: без RTM — CR не принят |
Вопрос–Ответ
В: Когда можно менять обязательные входные поля без MAJOR?
О: Никогда. Обязательное — всегда breaking → MAJOR или новый endpoint/версия топика.
В: Можно ли не повышать MINOR, если добавили необязательное поле?
О: Формально можно как PATCH, но рекомендуется MINOR, чтобы клиенты увидели новизну.
В: Как жить с несколькими версиями событий?
О: Поддерживайте additive-only эволюцию и default в новых полях; для кардинальных изменений — новый eventName.v2 и поэтапная миграция консьюмеров.
В: Кто пишет CHANGELOG?
О: Владелец артефакта (обычно SA вместе с Tech Lead). Это часть Definition of Done.
В: Сколько держать deprecated?
О: Зависит от контракта с клиентами. Практика: анонс ≥30 дней, поддержка 60–90 дней, затем отключение.
В: Надо ли хранить бизнес-обоснование в CR?
О: Да — это помогает CCB принимать решения и отслеживать «почему так сделали».
Практика (60–120 мин): оформить change request
Задание: подготовьте CR на изменение «Добавить customerEmail в PaymentRequest как обязательное поле (для чеков)».
Шаги:
- Заполните форму CR (из §4.2) с анализом влияния: это breaking → MAJOR; требуется /v2/payments или флаг-режим с альтернативным эндпоинтом.
- Сделайте диффы: OpenAPI v1 → v2 (новая required), обновите SRS/AC/BDD/RTM.
- Спроектируйте миграцию: параллельная публикация /v1 и /v2, гайд для клиентов, A/B включение UI поля; срок деактивации /v1.
- Подготовьте SQL/данные (если храните e-mail): колонка customer_email, валидация, приватность (PII).
- Обновите CHANGELOG и черновик release notes.
- Вынесите на CCB (решение/условия/сроки).
Критерии зачёта:
- Правильно определён тип изменения и bump.
- Есть полный impact analysis (API/данные/безопасность/DWH/наблюдаемость).
- Миграция обратима (фичефлаги/dual-run), есть дата deprecation.
- CHANGELOG/Release notes/RTM обновлены.
Шпаргалка (распечатайте)
- Docs-as-Code + Git + PR — единственный источник правды.
- Semver: добавили опциональное → MINOR; ломаете → MAJOR; фиксы → PATCH.
- Всегда показывайте диффы специализированных артефактов (OpenAPI/ER/DMN/Avro).
- Миграции: expand → switch → contract, фичефлаги, dual-run, откат через флаги.
- CHANGELOG и release notes — часть DoD.
- CCB решает по данным: ценность, совместимость, риски, план.
- RTM и AC/BDD обновляются в каждом CR.
