# Versioning

Copy as Markdown[View as Markdown](/docs/development/guides/adrs/versioning.md)

***

**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[​](#folder-structure "Direct link to Folder structure")

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

## Create a new version[​](#create-a-new-version "Direct link to 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[​](#version-pointer-syntax "Direct link to 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[​](#combining-versioning-with-status "Direct link to 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[​](#next-steps "Direct link to Next steps")

* [Model relationships between decisions](/docs/development/guides/adrs/relationships.md)
* [ADR frontmatter API reference](/docs/api/adr-api.md)