Deprecation policy
Deprecation policy for Q integrations.
Stability is declared per operation by the deployed capability registry and OpenAPI. The /v1 prefix alone is not a stability guarantee. Q platform maintainers own compatibility, and the capability ownership table assigns domain responsibility.
| Tier | Maintenance policy |
|---|---|
| Stable | Breaking changes require a documented successor, migration support and at least six months' notice. |
| Beta | Changes require release notes and explicit migration guidance; notice can be shorter. |
| Alpha | Experimental; may change or be withdrawn. |
Legacy signalling is implemented by app/core/deprecation.py: responses carry Deprecation: true, Sunset and a successor Link. The boolean is Q's existing compatibility format, not the structured date syntax of RFC 9740. Exact routes use the registry there; other /api/v1/* routes use its generic successor. A header is notice, not evidence that a replacement supports every legacy operation.
Do not remove a path solely because a date has passed. The owning team must verify usage, successor conformance, deployed notice and migration support before a separately reviewed removal. Security fixes can tighten access immediately; record the changed behaviour and recovery path in release notes.
See versioning, public contracts and capabilities. Historical migration dates remain in the legacy migration record; the runtime registry is the authority for emitted headers.