Skip to content

ADR_00012: Event Versioning Strategy – forward-compatible evoluce

Status: Proposed / Accepted
Date: 2025-12-30

Context

Architektura systému je založena na event-driven komunikaci mezi doménami.
Eventy jsou dlouhodobě perzistované, distribuované a konzumované více nezávislými službami.

V takovém prostředí:

  • nelze předpokládat synchronní nasazení všech konzumentů,
  • eventy mají dlouhou životnost,
  • změny struktury eventu mohou způsobit rozpad integrace,
  • neexistuje centrální bod, kde by bylo možné vynutit okamžitý upgrade.

Bez jasné strategie verzování by: - docházelo k nekompatibilním změnám, - vznikaly by skryté závislosti, - integrace by byly křehké a obtížně udržitelné.

Decision

Eventy jsou považovány za veřejné kontrakty

Každý event:

  • je součástí veřejného integračního rozhraní,
  • má dlouhodobou životnost,
  • nesmí být měněn nekompatibilním způsobem.

Event není interní implementační detail.

Povolen je pouze forward-compatible vývoj

Povoleny jsou pouze změny, které:

  • přidávají nové nepovinné atributy,
  • nemění význam existujících polí,
  • nemění semantiku eventu.

Zakázáno je:

  • mazání polí,
  • změna významu existujícího pole,
  • změna typu pole,
  • změna významu eventu bez nové verze.

Verzování eventů

Každý event:

  • má explicitní verzi (např. v1, v2)
  • verze je součástí názvu nebo metadat
  • nová verze = nový typ eventu

Příklad:

  • OrderCreated.v1
  • OrderCreated.v2

Staré verze mohou existovat paralelně, dokud existují konzumenti.

Zákaz „breaking changes“ bez migračního plánu

Jakákoliv nekompatibilní změna musí mít:

  • jasně popsanou migrační strategii,
  • dobu souběhu verzí,
  • plán odstranění staré verze,
  • zpětnou kompatibilitu po přechodné období.

Povinné testy kompatibility

Pro každý event platí:

  • kontraktové testy mezi producentem a konzumentem,
  • validace schématu (např. JSON Schema / Avro),
  • testy zpětné kompatibility.

Event bez testů kompatibility nesmí být publikován.

Consequences

Pozitiva

  • Stabilní integrační rozhraní
  • Možnost nezávislého nasazování služeb
  • Minimalizace regresí
  • Předvídatelná evoluce systému
  • Čitelnost a dlouhodobá udržitelnost eventů

Negativa

  • Vyšší disciplína při návrhu eventů
  • Nutnost správy verzí
  • Více testů a validační logiky
  • Delší životní cyklus starých verzí

Rationale

Rozhodnutí Důvod
Event jako kontrakt Zajišťuje stabilitu integrace
Forward-only změny Zabraňuje rozbití konzumentů
Explicitní verze Umožňuje paralelní provoz
Zákaz breaking changes Ochrana celého ekosystému
Povinné testy Prevence regresí

Considered Alternatives

  • Backward-compatible changes

    • Stará verze eventu je stále platná, nové konzumenty mohou používat nová pole.
    • Výhody:
      • Starší služby nemusí být okamžitě upraveny.
      • Podporuje postupnou migraci.
    • Nevýhody:
      • Staré pole stále musí být podporováno → vyšší komplexita.
      • Může vést k duplicitní logice ve více verzích.

  • Full version replacement (breaking change)

    • Starý event je nahrazen úplně novou verzí (v2), stará verze je ukončena.
    • Výhody:
      • Čistý a jednoznačný kontrakt pro nové konzumenty.
      • Možnost úprav eventu bez omezení.
    • Nevýhody:
      • Nutnost koordinace mezi všemi konzumenty.
      • Riziko výpadků, pokud staré služby nejsou připraveny.

  • Transitive changes

    • Event se mutuje bez jakýchkoliv pravidel
    • Výhody:
      • Není třeba verzování
      • Možnost úprav eventu bez omezení.
    • Nevýhody:
      • Neudržitelný kontrakt