42 lines
2.0 KiB
Markdown
42 lines
2.0 KiB
Markdown
# API deprecation policy — 0pt
|
|
|
|
BACKLOG P6 (API-24). There is exactly one prior breaking-ish change in this
|
|
repo's history to learn from: `services/api/orchestrator/main.py` moved from
|
|
`src/orchestrator` (docs/09-build-plan.md Phase 0) — internal, pre-contract,
|
|
no external consumers yet. This policy is written before it's needed for a
|
|
real consumer, on purpose (BACKLOG's own framing: "cheaper to write the
|
|
policy than to clean up after breaking someone").
|
|
|
|
## What counts as breaking
|
|
|
|
- Removing a path, operation, or required request/response field from
|
|
`contracts/openapi.yaml`.
|
|
- Narrowing an accepted value (enum shrink, type tightening) on a request field.
|
|
- Changing a response field's meaning without changing its name/type.
|
|
- Changing default auth/tenant behavior on an existing route (e.g. what
|
|
BACKLOG P0-4 fixed — the reverse of a break, but the same class of change).
|
|
|
|
Not breaking: adding an optional field, adding a new path, widening an
|
|
accepted value, adding a new enum member a client can ignore.
|
|
|
|
## Process
|
|
|
|
1. Mark the field/path `deprecated: true` in `contracts/openapi.yaml` with an
|
|
`x-siax-deprecated-since` date and a one-line replacement pointer.
|
|
2. Keep the deprecated shape working for **at least one release cycle**
|
|
after the replacement ships (see `CHANGELOG.md` once real releases/tags
|
|
exist — BACKLOG P1-3).
|
|
3. Announce in `CHANGELOG.md`'s `[Unreleased]` section before merge, not
|
|
after.
|
|
4. Only remove once nothing in this repo's own consumers (Protosell/FiveCRM,
|
|
VehIQ per `CLAUDE.md`) is verified to depend on the old shape — "verified"
|
|
means checked against those repos, not assumed silent.
|
|
|
|
## What this repo does NOT have yet
|
|
|
|
No consumers are known to be live against this contract yet
|
|
(`docs/architecture/ARCHITECTURE.md` §2 "Beroenden nedåt": "Inga sådana
|
|
anrop finns i det här repot" — unverified downstream). This policy exists
|
|
so the first real breaking change has a process to follow, not because one
|
|
has happened.
|