# 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