Jon Chery
d830357230
---ci--- project: acdl phase: 21 milestone: v1.6 status: execute ---/ci--- Restructure docs/ into a Jekyll-style GitHub Pages site: - docs/_config.yml (Pages config + nav, excludes internal/) - docs/index.md (landing: platform + consumer model, Features, Roadmap) - docs/modules/index.md (catalog: primitives + modules, normalized terms) - docs/contracts/index.md (schema, fields, sample, multi-contract) - docs/pipeline/index.md (CI + deploy pipeline, stages mermaid, streaming) - docs/pipeline/versioning.md (module + deploy-pipeline versioning) - docs/environments/index.md (platform-managed envs + onboarding, REQ-61) - docs/consumer-guide.md (renamed from CONSUMER_GUIDE.md; GitHub-only, no .gitea, forge->platform runners, L2->modules, composition->pattern, updated mermaid with security-checks + infrastructure-apply) - docs/architecture.md (consolidated from architecture.md + architecture-v1.0.md, current-architecture only, normalized terms: primitives/modules, platform runners, no L1/L2/forge/gitea in prose) - Removed docs/architecture-v1.0.md (consolidated) + docs/CONSUMER_GUIDE.md (renamed). No .ciagent/ or .gitea/ references in docs/. Consumer-facing terminology normalized (L2->modules, L1->primitives, composition->pattern, forge-> platform runners).
2.2 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 uses: tag)
The central deploy pipeline is referenced by a floating MAJOR + MINOR tag in a consumer's contract and CI definition:
uses: acdl/pipelines/deploy.yaml@v1.4
Version constraints cannot be expressed inside the contract, so the tag in
uses: is the only immutability lever a consumer has.
Unversioned references are discouraged. Do not use @main or a bare
acdl/pipelines/deploy.yaml — 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.