0pt/docs/api/DEPRECATION_POLICY.md

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.