Jon Chery
eef8761658
---ci--- project: acdl phase: 19 milestone: v1.14 status: complete requirements: covered: [REQ-153] partial: [] ---/ci---
2.3 KiB
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.
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:
jobs:
deploy:
uses: acdl/.github/workflows/deploy.yml@v1.13
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.