continuous-intelligence/acdl
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 128 Wiki Activity

docs(P19): complete documentation-sync-v1.14 phase (v1.13.23)

Browse Source 
---ci---
project: acdl
phase: 19
milestone: v1.14
status: complete
requirements:
  covered: [REQ-153]
  partial: []
---/ci---
This commit is contained in:
Jon Chery
2026-07-29 21:30:41 +00:00
parent df1b004a46
commit eef8761658
8 changed files with 115 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+1 -1
View File
@@ -230,7 +230,7 @@ change to the modules/stack/confidence/audit.
- A MAJOR bump requires a new registry entry (immutable publication); the
old entry enters a 12-month deprecation window.
- The central deploy pipeline is referenced by a floating MAJOR + MINOR tag
(e.g. `@v1.6`); patch fixes flow within the tag, breaking changes land
(e.g. `@v1.13`); patch fixes flow within the tag, breaking changes land
under the next MINOR tag.
See [Versioning](pipeline/versioning) for the consumer-facing details.
docs/consumer-guide.md
+12 -12
View File
@@ -19,7 +19,7 @@ definitions.
```mermaid
flowchart LR
A["your repo<br/>(app code + contracts + CI definitions)"] -->|uses: acdl/.github/workflows/deploy.yml@v1.9| B
A["your repo<br/>(app code + contracts + CI definitions)"] -->|uses: acdl/.github/workflows/deploy.yml@v1.13| B
B["platform runners<br/>(modules + pipelines + adapters + schemas)"] -->|contract -&gt; resolver -&gt; stack -&gt; adapter<br/>-&gt; security checks -&gt; infrastructure plan -&gt; policy checks<br/>-&gt; confidence -&gt; apply -&gt; evidence event| C
C["your resources in AWS"]
```
@@ -27,7 +27,7 @@ flowchart LR
## Versioning the `uses:` reference
The central deployment pipeline is **always versioned with floating MAJOR
and MINOR tags** (e.g. `acdl/pipelines/contract.yml@v1.9`). Version
and MINOR tags** (e.g. `acdl/pipelines/contract.yml@v1.13`). Version
constraints cannot be expressed inside the contract, so the tag in
`uses:` is the only immutability lever a consumer has. See
[Versioning](pipeline/versioning) for the full rationale.
@@ -47,7 +47,7 @@ platform-managed. See [Environments](environments/).
environment is bound, your first pipeline run emits a friendly onboarding
prompt. See [Environments](environments/).
- **Authorization to reference the central pipeline.** Onboarding grants
your repo the right to `uses: acdl/.github/workflows/deploy.yml@v1.9`.
your repo the right to `uses: acdl/.github/workflows/deploy.yml@v1.13`.
Contact the platform team if you have not been onboarded.
## Step 1 — Create a consumer repo
@@ -94,7 +94,7 @@ ACDL deployment workflow with a **versioned tag** (floating MAJOR + MINOR):
```yaml
jobs:
deploy:
uses: acdl/.github/workflows/deploy.yml@v1.9
uses: acdl/.github/workflows/deploy.yml@v1.13
with:
contract: .acdl/contract.yml
environment: dev
@@ -140,7 +140,7 @@ name: microservice
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `uses` | string | yes | Reference to the central deployment pipeline, **versioned** with a floating MAJOR+MINOR tag (e.g. `acdl/pipelines/contract.yml@v1.9`). Bare or `@main` references are discouraged. See [Versioning](pipeline/versioning). |
| `uses` | string | yes | Reference to the central deployment pipeline, **versioned** with a floating MAJOR+MINOR tag (e.g. `acdl/pipelines/contract.yml@v1.13`). Bare or `@main` references are discouraged. See [Versioning](pipeline/versioning). |
| `module` | string | yes | Module name from the registry — any primitive or module (e.g. `static-assets`, `microservice`, `s3`). See the [module catalog](modules/). |
| `environment` | string | yes | The platform-managed environment to deploy to (e.g. `dev`). See [Environments](environments/). |
| `inputs` | object | yes | Module-specific inputs (see the module's README). |
@@ -177,14 +177,14 @@ on:
branches: [main]
jobs:
deploy:
uses: acdl/.github/workflows/deploy.yml@v1.9
uses: acdl/.github/workflows/deploy.yml@v1.13
with:
contract: .acdl/contract.yml
```
That is the entire consumer-side workflow. When you push to `main`:
1. The platform runner resolves `uses: acdl/.github/workflows/deploy.yml@v1.9`
1. The platform runner resolves `uses: acdl/.github/workflows/deploy.yml@v1.13`
to the reusable workflow **at the pinned tag**.
2. A **platform-provided runner** checks out **your** repo.
3. The runner checks out the **ACDL platform repo** into the workspace —
@@ -326,8 +326,8 @@ per-module extension points. Common examples:
| Contract schema | `schemas/contract.schema.json` | JSON Schema for consumer contracts. |
| Stack schema | `schemas/stack.schema.json` | JSON Schema for the resolved stack instance. |
| Module catalog | [modules/](modules/) | All primitives and modules. |
| Sample contract | `contracts/static-assets.yaml` | The reference example contract (uses `@v1.9`). |
| Sample contract | `contracts/microservice.yaml` | The microservice example contract (uses `@v1.9`). |
| Sample contract | `contracts/static-assets.yaml` | The reference example contract (uses `@v1.13`). |
| Sample contract | `contracts/microservice.yaml` | The microservice example contract (uses `@v1.13`). |
| Module examples | `modules/<name>/examples/` | Validated per-module example contracts (`simple.yaml` + `complex.yaml`). |
| Contract resolver | `core/contract_resolver.py` | Resolves contracts to stack instances. |
| Angine adapter | `adapters/terraform/adapter.py` | Compiles stack instances to infrastructure. |
@@ -353,7 +353,7 @@ destruction:
use `mode: decommission` with the `changeRequestId` input:
```yaml
uses: acdl/.github/workflows/deploy.yml@v1.8
uses: acdl/.github/workflows/deploy.yml@v1.13
with:
contract: .acdl/contract.yml
mode: decommission
@@ -421,7 +421,7 @@ name: static-assets
```
**Shape 2 — single contract + `environment` workflow input:** the
reusable deploy workflow (`acdl/.github/workflows/deploy.yml@v1.9`)
reusable deploy workflow (`acdl/.github/workflows/deploy.yml@v1.13`)
declares an `environment` input. When non-empty, it overrides the
contract's `environment` field at load time (before interpolation), so
the same contract can be promoted by passing a different environment:
@@ -436,7 +436,7 @@ on: workflow_dispatch:
required: true
jobs:
deploy-qa:
uses: acdl/.github/workflows/deploy.yml@v1.9
uses: acdl/.github/workflows/deploy.yml@v1.13
with:
environment: qa
contract: .acdl/contract.yml
docs/pipeline/index.md
+1 -1
View File
@@ -39,7 +39,7 @@ It is exposed to consumer repos as a **reusable workflow**:
- `.github/workflows/deploy.yml` — GitHub Actions (production)
A consumer repo invokes the reusable workflow via a **versioned tag**
(floating MAJOR + MINOR, e.g. `acdl/.github/workflows/deploy.yml@v1.6`).
(floating MAJOR + MINOR, e.g. `acdl/.github/workflows/deploy.yml@v1.13`).
The workflow checks out the consumer repo, then checks out the ACDL platform
repo into the runner workspace, and runs `scripts/run_platform.sh` against
the consumer's contract. The consumer never clones the platform repo or
docs/pipeline/versioning.md
+1 -1
View File
@@ -26,7 +26,7 @@ tag** in a consumer's CI workflow definition:
```yaml
jobs:
deploy:
uses: acdl/.github/workflows/deploy.yml@v1.6
uses: acdl/.github/workflows/deploy.yml@v1.13
with:
contract: .acdl/contract.yml
```