Skip to main content

Versioning

View as Markdown
Added in eventcatalog@3.42.0

ADRs follow the same versioning pattern as other EventCatalog resources. The root index.mdx always represents the current version, and older versions live in a versioned subfolder.

Folder structure​

adrs/
  choose-kafka/
    index.mdx                  ← current version (2.0.0)
    versioned/
      1.0.0/
        index.mdx              ← previous version

Create a new version​

When revising an ADR, copy the current file into a new versioned folder, then update the root file.

mkdir -p adrs/choose-kafka/versioned/1.0.0
cp adrs/choose-kafka/index.mdx adrs/choose-kafka/versioned/1.0.0/index.mdx

# Now edit adrs/choose-kafka/index.mdx
# - bump version to 2.0.0
# - update status and content

Version pointer syntax​

When referencing a specific version in supersedes, supersededBy, amends, amendedBy, or related, use the id and version fields.

supersedes:
  - id: choose-kafka
    version: 1.0.0

Omitting version defaults to latest.

Combining versioning with status​

A common pattern is to use versioning together with the superseded status to preserve the full history of a decision.

versioned/1.0.0/index.mdx
---
id: choose-kafka
version: 1.0.0
status: superseded
supersededBy:
  - id: choose-kafka
    version: 2.0.0
---
index.mdx (current)
---
id: choose-kafka
version: 2.0.0
status: accepted
supersedes:
  - id: choose-kafka
    version: 1.0.0
---

EventCatalog shows a warning banner on the old version's page and links to the new one.

Next steps​