9f6e6f7fb3
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Signals CI & Image / signals-ci (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Policy Simulation / policy-simulate (push) Has been cancelled
SDK Publish & Sign / sdk-publish (push) Has been cancelled
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
devportal-offline / build-offline (push) Has been cancelled
59 lines
2.7 KiB
Markdown
59 lines
2.7 KiB
Markdown
# Contributing to API Contracts
|
|
|
|
Last updated: 2025-11-25
|
|
|
|
## Scope
|
|
Guidelines for editing service OpenAPI specs, lint rules, compatibility checks, and release artefacts across StellaOps services.
|
|
|
|
## Required tools
|
|
- Node.js 20.x + pnpm 9.x
|
|
- Spectral CLI (invoked via `pnpm api:lint` in `src/Api/StellaOps.Api.OpenApi`)
|
|
- `diff2html` (optional) for human-friendly compat reports
|
|
|
|
## Workflow (per change)
|
|
1) Edit service OAS under `src/Api/StellaOps.Api.OpenApi/services/<service>/*.yaml`.
|
|
2) Run lint + compose + compat + changelog from repo root:
|
|
```bash
|
|
pnpm --filter @stella/api-openapi api:lint # spectral
|
|
pnpm --filter @stella/api-openapi api:compose # build stella.yaml
|
|
pnpm --filter @stella/api-openapi api:compat # compare against baseline
|
|
pnpm --filter @stella/api-openapi api:changelog # generate digest/signature
|
|
```
|
|
3) Review outputs:
|
|
- `out/api/stella.yaml` (composed spec)
|
|
- `out/api/compat-report.json` (+ `.html` if generated)
|
|
- `out/api/changelog/` (digest + signature for SDK pipeline)
|
|
4) Update examples: ensure request/response examples exist for changed endpoints; add to `examples/` directories.
|
|
5) Commit changes with notes on breaking/additive results; attach compat report paths.
|
|
|
|
## Lint rules (Spectral)
|
|
- House rules live in `.spectral.yaml` under `src/Api/StellaOps.Api.OpenApi`.
|
|
- Enforce: tagged operations, error envelope shape, schema refs reuse, pagination tokens, RBAC scopes, standard headers (`traceparent`, `x-correlation-id`).
|
|
|
|
## Compatibility checks
|
|
- Baseline file: `stella-baseline.yaml` (kept in repo under `out/api/` and updated per release).
|
|
- `api:compat` flags additive/breaking/unchanged deltas. Breaking changes require approval from API Governance Guild and affected service guilds.
|
|
|
|
## Examples & error envelopes
|
|
- Every operation must have at least one request + response example.
|
|
- Error responses must use the standard envelope (`error.code`, `error.message`, `trace_id`).
|
|
|
|
## Offline/air-gap
|
|
- Keep `pnpm-lock.yaml` pinned; store `node_modules/.pnpm` cache in Offline Kit when needed.
|
|
- Include composed spec, compat report, and changelog artefacts in offline bundles under `offline/api/` with checksums.
|
|
|
|
## Release handoff
|
|
- Deliverables for each release:
|
|
- `out/api/stella.yaml`
|
|
- `out/api/compat-report.json` (+ `.html` if produced)
|
|
- `out/api/changelog/*` (digest, signature, manifest)
|
|
- Provide SHA256 checksums for artefacts and note `source_commit` + `timestamp` in release notes.
|
|
|
|
## Review checklist
|
|
- [ ] Lint clean (`api:lint`)
|
|
- [ ] Examples present for changed endpoints
|
|
- [ ] Compat report reviewed (additive/breaking noted)
|
|
- [ ] Changelog artefacts generated + checksums
|
|
- [ ] Offline bundle artefacts staged (if required)
|
|
- [ ] Docs/UI/SDK owners notified of breaking changes
|