# Versioning

ACDL uses two versioning schemes: one for modules, one for the deploy
pipeline. Both matter to a consumer.

## Module versioning

Primitives and modules use **semver** with three triggers:

- **interface → MAJOR** — a breaking change to the module's inputs/outputs.
- **behavior → MINOR** — a backward-compatible behavior change.
- **lifecycle → PATCH** — a fix or internal change.

A MAJOR bump requires a **new registry entry** (immutable publication); the
old entry enters a **12-month deprecation window**. A module pins its
primitives by `name@semver`; the resolver picks the highest compatible.

Module versions are tracked in
[`registry.json`](https://github.com/acdl/acdl/blob/main/modules/registry.json).

## Deploy-pipeline versioning (the CI workflow `uses:` tag)

The central deploy pipeline is referenced by a **floating MAJOR + MINOR
tag** in a consumer's CI workflow definition:

```yaml
jobs:
  deploy:
    uses: acdl/.github/workflows/deploy.yml@v1.6
    with:
      contract: .acdl/contract.yml
```

The version pin lives in the CI workflow reference (not in the contract
itself — the contract no longer carries a `uses:` field). The CI workflow
`uses:` tag is the only immutability lever a consumer has.

**Unversioned references are discouraged.** Do not use `@main` or a bare
`acdl/.github/workflows/deploy.yml` — `main` is constantly updated and can
cause unexpected failures. Pinning to a MAJOR+MINOR tag means:

- **Immutability** — the pipeline behavior you tested is the behavior you
  get. Patch fixes flow within the tag; breaking changes land under the
  next MINOR tag (`@v1.5`), which you opt into explicitly.
- **Resilience** — your deployment does not break because an unrelated
  change landed on `main`.
- **Reproducibility** — your setup is stable. You upgrade on your schedule
  by bumping the tag.

## When a new tag is released

When a new MINOR tag is released (e.g. `@v1.5`), review its changelog and
bump your `uses:` reference when ready. The old tag continues to receive
patch fixes until the next MINOR tag.

## Production-bound references

For production-bound workflows, the platform resolves the current tag to its
SHA (tag for dev/qa, SHA for prod). This prevents a silent patch from
changing a production deployment. The platform provides a CLI command for
the tag → SHA resolution.