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

Release Engineering And Migrations — Релизы, совместимость и эволюция схем

Версия: 1.0
Дата: 24.04.2026
Статус: Готов к обсуждению

Назначение документа​

Этот документ фиксирует execution-level правила для release engineering, schema and contract migrations, compatibility windows, rollout safety, replay-aware changes и safe production evolution платформы vitrip.store.

Его задача — определить:

  • как платформа должна выпускать изменения в живую систему без разрушения truth boundaries;
  • как должны соотноситься code changes, schema changes, contract changes и migration steps;
  • как учитывать impact на supplier ingestion, quote/booking flows, settlement and reconciliation, partner contracts и operational queues;
  • как должны работать staged rollout, rollback, forward-fix и post-release verification;
  • какие классы изменений требуют особой дисциплины.

Этот документ не про YAML pipeline и не про git flow как самоцель. Это документ о безопасной эволюции живой industrial платформы.

Опорные документы​

Почему Этот Документ Нужен Отдельно​

После фиксации deployment, observability и settlement execution слой уже нельзя считать, что safe change происходит сам собой.

Платформа должна менять:

  • schema;
  • contracts;
  • business logic;
  • supplier processing;
  • quote/repricing rules;
  • booking transitions;
  • settlement event generation;

без потери:

  • truth discipline;
  • compatibility;
  • replayability;
  • auditability;
  • operational recoverability.

Главный Принцип Release Engineering​

Платформа должна выпускать изменения так, будто она уже живёт в нескольких связанных реальностях одновременно:

  • persistent truth;
  • public and managed contracts;
  • supplier-driven inputs;
  • operational queues;
  • financial and settlement traces.

Поэтому ключевой принцип такой:

изменение считается безопасным только тогда, когда понятны его forward path, compatibility window, rollback or forward-fix strategy, observability signals и truth impact.

Release Classes​

1. Low-Risk Changes​

  • pure presentation changes;
  • documentation-linked internal UI improvements;
  • non-critical dashboards;
  • additive internal telemetry.

2. Medium-Risk Changes​

  • search and offer projection logic;
  • non-breaking partner or agency contract additions;
  • ingestion normalization refinements with replay safety;
  • new internal operator fields and views.

3. High-Risk Changes​

  • quote semantics;
  • repricing logic;
  • booking state machine behavior;
  • settlement event generation;
  • identity / scope boundaries;
  • supplier matching logic with canonical impact;
  • schema changes on transactional or audit-critical data.

4. Critical Change Programs​

Это не один deploy, а multi-step coordinated rollout:

  • large schema evolution;
  • public contract deprecation;
  • supplier integration refactor with replay impact;
  • migration of financial trace model;
  • changes affecting booking and settlement together.

Change Dimensions​

Любой серьёзный rollout должен быть оценён минимум по пяти измерениям:

1. Schema Impact​

  • adds fields/tables only;
  • changes semantics of existing fields;
  • backfills old truth;
  • changes retention-critical structures.

2. Contract Impact​

  • additive;
  • behaviorally changed but schema-compatible;
  • breaking for partner or managed surfaces;
  • async event semantic change.

3. Execution Impact​

  • affects ingestion;
  • affects offer/quote path;
  • affects booking path;
  • affects reconciliation / settlement;
  • affects internal operator flows.

4. Recovery Impact​

  • can be rolled back cleanly;
  • requires forward-fix only;
  • requires data correction event;
  • requires replay or revalidation wave.

5. Surface Impact​

  • internal only;
  • agency;
  • partner;
  • B2C;
  • cross-surface.

Release Unit Discipline​

Release unit должен быть достаточно мал, чтобы им можно было безопасно управлять, и достаточно целостен, чтобы не разрывать доменную логику.

Release Unit Must Declare​

  • affected contours;
  • affected truth classes;
  • required schema state;
  • required feature flags or staged gates;
  • required operator watch;
  • post-release verification criteria.

Schema Migration Principles​

Expand Before Contract​

Сначала добавлять:

  • новые таблицы;
  • новые поля;
  • новые indexes;
  • новые event sinks;

и только потом переключать runtime behavior.

Avoid Big-Bang Replace​

Нельзя в одном шаге:

  • удалить старую truth structure;
  • переключить всю логику;
  • переписать historical meaning;
  • считать rollback возможным без доказательства.

Migration Must Respect Truth Classes​

Особенно осторожно должны меняться:

  • quotes;
  • bookings;
  • settlement traces;
  • governance cases;
  • supplier trace lineage;
  • tenant and access boundaries.

Contract Evolution Principles​

External Stable Contracts​

Требуют:

  • additive-first evolution;
  • explicit deprecation window;
  • partner-facing communication;
  • version discipline;
  • semantic compatibility checks.

Managed Application Contracts​

Могут меняться быстрее, но должны сохранять:

  • workflow continuity;
  • actor/scope correctness;
  • quote/booking semantics;
  • operator explainability.

Internal Service Contracts​

Могут быть более подвижными, но при этом обязаны сохранять:

  • replay safety;
  • event meaning stability where critical;
  • observability continuity;
  • migration-aware compatibility during rollout windows.

Replay-Aware Changes​

Платформа с supplier ingestion не может мыслить изменения без replay impact.

Любое Изменение Ingestion / Matching / Normalization Должно Ответить​

  • что случится с уже сохранённым raw trace;
  • требуется ли replay;
  • может ли replay изменить canonical truth;
  • может ли replay вызвать repricing wave;
  • может ли replay вызвать publication holds;
  • может ли replay задеть settlement interpretation.

Safe Replay Change Pattern​

new logic introduced
  → shadow evaluation or bounded test replay
  → compare with previous outcomes
  → rollout with observability gates
  → targeted replay where justified
  → review discrepancy wave if needed

Quote / Booking Change Discipline​

Изменения в quote and booking paths требуют особой строгости.

Для Quote Changes Должно Быть Ясно​

  • меняется ли quoted promise meaning;
  • меняется ли repricing threshold or reason model;
  • меняется ли breakdown visibility;
  • потребуется ли invalidate existing quotes;
  • как это будет видно agency / partner / internal surfaces.

Для Booking Changes Должно Быть Ясно​

  • меняется ли state machine;
  • меняется ли idempotency handling;
  • меняется ли unknown external state treatment;
  • меняется ли coupling with settlement events;
  • нужен ли special recovery playbook.

Settlement-Sensitive Changes​

Это один из самых опасных классов изменений.

Settlement-Sensitive Changes Include​

  • event generation logic;
  • fee/commission/revenue-share interpretation;
  • refund reversal rules;
  • amendment delta handling;
  • FX / rounding logic;
  • reconciliation classification rules.

Для Таких Изменений Обязательны​

  • forward-fix preference over blind rollback where data already produced;
  • explicit comparison of old and new financial outcomes;
  • discrepancy monitoring after rollout;
  • finance/reconciliation owner involvement;
  • correction-event strategy.

Rollout Strategies​

1. Dark / Shadow Evaluation​

Подходит для:

  • repricing logic changes;
  • matching changes;
  • classification changes;
  • settlement classification changes.

2. Feature-Gated Rollout​

Подходит для:

  • new surface semantics;
  • new booking or quote behavior;
  • partner-specific gradual enablement;
  • internal operator tooling changes.

3. Canary / Cohort Rollout​

Подходит для:

  • traffic-bearing path changes;
  • supplier-specific changes;
  • tenant or partner cohort rollout;
  • high-risk runtime behavior shifts.

4. Migration Then Cutover​

Подходит для:

  • schema expansion;
  • data copy / backfill;
  • read-path switch;
  • write-path switch;
  • eventual removal of legacy path.

Rollback And Forward-Fix​

Не каждый change type должен откатываться одинаково.

Rollback Is Reasonable When​

  • state not yet materially rewritten;
  • no external promises violated;
  • no settlement-significant outputs emitted;
  • old code and old schema still compatible.

Forward-Fix Is Preferable When​

  • booking or settlement events already emitted;
  • data corrections are required;
  • rollback would deepen semantic inconsistency;
  • new path only needs targeted repair.

Correction Event Model​

Для settlement and truth-sensitive flows часто safer:

  • issue correction;
  • mark discrepancy;
  • reconcile operationally;

чем “откатить код и забыть”.

Release Gates​

Pre-Release Gates​

  • schema compatibility reviewed;
  • contract impact reviewed;
  • observability probes ready;
  • rollback/forward-fix decision made;
  • owner-on-watch assigned.

During-Release Gates​

  • live error signals within threshold;
  • queue growth within threshold;
  • quote/booking anomalies absent or bounded;
  • supplier degradation not amplified;
  • settlement-sensitive metrics stable.

Post-Release Gates​

  • no abnormal discrepancy wave;
  • no unexplained publication holds;
  • no partner-visible semantic break;
  • no unreconciled booking surge attributable to release.

Migration Verification​

Миграция считается успешной не тогда, когда SQL отработал, а когда подтверждены:

  • schema readiness;
  • code compatibility;
  • domain-path correctness;
  • queue stability;
  • absence of hidden truth corruption.

Verification Must Include​

  • schema state checks;
  • contract smoke tests;
  • quote path checks;
  • booking path checks;
  • reconciliation signal checks;
  • replay-sensitive path checks where relevant.

Post-Release Observation Window​

Для medium/high-risk changes должен существовать observation window.

During Observation Window Track​

  • quote expiry and repricing anomalies;
  • booking pending/unknown spikes;
  • supplier mismatch signals;
  • queue aging;
  • reconciliation drift;
  • partner/agency support incidents.

Release Ownership​

Engineering Owner​

Owns code and rollout mechanics.

Domain Owner​

Owns semantic correctness of changed behavior.

Operations Owner​

Owns live monitoring and incident coordination.

Finance / Reconciliation Owner​

Must be involved for settlement-sensitive changes.

Supplier Operations Owner​

Must be involved for supplier-model changes with replay or production feed consequences.

Relationship To Other Operations Documents​

Этот документ замыкает execution-baseline вместе с:

Распределение ролей между ними теперь такое:

  • deployment определяет runtime and rollout environment model;
  • settlement-and-reconciliation определяет finance-grade operational reality;
  • observability-and-incident-response определяет detection, triage and recovery;
  • release-engineering-and-migrations определяет safe change discipline.

Текущий Практический Вывод​

Платформа vitrip.store должна выпускать изменения не как “новый код плюс миграция”, а как управляемое изменение живой системы, где:

  • contracts имеют compatibility cost;
  • supplier traces имеют replay cost;
  • quotes and bookings имеют promise cost;
  • settlement traces имеют correction cost;
  • observability должна заранее показывать, что release пошёл не туда.

Именно эта дисциплина позволяет industrial платформе эволюционировать быстро, не разрушая доверие к своим данным, обещаниям и operational truth.

Уточнение под Фазы 4–7 (28.04.2026) — связи с canary, SLA gates, isolation, security​

Документ опубликован 24.04.2026 в Фазе 3 как baseline release engineering. После Фаз 4–7 release дисциплина интегрирована со специализированными доменами; эта секция фиксирует обязательные связи.

Связь с deployment shape по фазам​

operations/deployment.md (Фаза 7 переработан, версия 3.0) определяет 4 фазы инфраструктуры. Release engineering учитывает фазу:

  • Фаза 1 (Bootstrap) — single cluster, простые rolling deployments;
  • Фаза 2 (Service isolation) — multi-AZ, blue-green deployments возможны;
  • Фаза 3 (Workload-specific) — canary с tenant-aware traffic shifting;
  • Фаза 4 (Multi-region) — region-by-region rollout с health checks.

Связь с tier-зависимыми canary правилами​

reference/api-as-product.md (Фаза 4) определяет 4 API tier. Каноничное правило (см. operations/deployment.md):

  • Enterprise tier — first canary (counter-intuitive, но согласовано с Stripe/Twilio practices: Enterprise integrated глубже, регрессии у них раньше детектируются);
  • Professional — early canary (после Enterprise);
  • Starter — middle canary (после Professional, при стабильных metrics);
  • Free — last canary (lowest priority, but широчайшее воздействие).

Это переписывает обычное правило «начинаем с малого процента трафика любых пользователей» — canary stages rolling per tier.

Связь со SLA gates (release gates)​

operations/sla-and-on-call-model.md (Фаза 6) определяет error budget per tier. Release gate теперь включает:

  • Error budget check — если tenant tier уже использовал более 50% месячного error budget, release требует дополнительное approval;
  • SLI baseline check — current SLI metrics не должны быть в degraded state перед release;
  • Burn rate alert — при автоматическом увеличении burn rate в canary, automatic rollback.

Release gates документа теперь дополняются:

  • ✅ canary metrics не нарушают SLA;
  • ✅ error budget доступен для tier;
  • ✅ no active incidents (см. runbooks-incident-playbooks.md);
  • ✅ SLA reporting не показывает degradation в predeploy window.

Связь с DR drills​

operations/disaster-recovery-and-capacity.md (Фаза 6) — DR procedures используют release engineering primitives:

  • Ephemeral namespace для restore drill — same pattern как ephemeral deployment для testing;
  • Blue-green switch — same pattern как promotion из canary;
  • Rollback capability — same pattern.

Release engineering и DR разделяют infrastructure primitives, но имеют разные goals.

Связь с booking state machine migrations​

reference/booking-state-machine.md (Фаза 5) — 14 каноничных состояний. Migration discipline для booking:

  • Forward-compatible — новые state names добавляются как дополнительные, существующие транзиции остаются;
  • Backward-compatible queries — old code читает booking с новыми states (получает sentinel value unknown_state вместо crash);
  • State migration window — старая логика поддерживается в течение compatibility window (минимум 30 дней);
  • No state collapse — нельзя сливать состояния (например, объединить cancel_requested и cancelled в одно cancelled) без major version bump.

Связь с Tour Builder saga migrations​

reference/tour-builder-operational-model.md (Фаза 5) — saga migrations особенно опасны:

  • Active sagas — running saga при deployment не должна сломаться;
  • Backward-compatible compensation — новая логика compensation должна корректно обрабатывать sagas, начатые старой версией;
  • Saga state journal — append-only, миграции читают, не меняют существующие entries.

Связь с tenant isolation​

reference/multi-tenant-isolation-strength.md (Фаза 5) — release affects tenant isolation:

  • logical tenants — release коснётся всех одновременно;
  • dedicated_compute tenants — release per dedicated namespace, независимо;
  • dedicated_infrastructure tenants — release per dedicated cluster, never simultaneously с shared (Enterprise обещание);
  • Per-tenant rollback — для dedicated_compute+ возможна индивидуальная отмена.

Связь с supply chain security​

reference/security-architecture.md (Фаза 10) — release pipeline должен:

  • SBOM generation для каждого release (Software Bill of Materials);
  • Vulnerability scanning dependencies до merge;
  • Code signing — Git commits + container images через Cosign;
  • Build provenance — reproducible builds где возможно;
  • Trusted base images — distroless или minimal images, signed.

Связь с compliance audit trail​

reference/compliance-and-legal.md (Фаза 4) требует audit trail каждого release для SOC 2 / ISO 27001:

  • кто approved release;
  • какие changes включены;
  • какие tests passed;
  • canary metrics на момент promotion;
  • rollback events если были;
  • SBOM и vulnerability scan results.

Release audit log — Tier 1 retention (7 лет, immutable WORM).

Связь с partner deprecation policy​

reference/api-as-product.md (Фаза 4) — deprecation policy:

  • минимум 6 месяцев notice для major versions (Free/Starter);
  • минимум 12 месяцев для Professional;
  • custom timeline для Enterprise (часть контракта);
  • migration tools — diff specifications, compatibility shims, migration guides.

Release engineering pipeline должен enforced эти timelines через automated checks (no production deployment с removed deprecated endpoint раньше end-of-life date).

Каноничный итог уточнения​

Release engineering baseline теперь интегрирован с:

Уточнение выполнено через no-destruction.