Repository: cppa-cursor-browser
Assignee: Brad @bradjin8
Points: 1
Severity: Medium
Problem
The project has no documented API deprecation process. The Flask route handlers lack parameter documentation, and there is no mechanism to warn consumers when endpoints, parameters, or response shapes will change. Combined with the absence of a versioning policy (item 9), consumers of the HTTP API cannot determine the current contract and will receive no warning when it changes. For a tool at version 0.1.0 this is expected, but the production-level deployment documentation creates expectations the versioning posture does not support.
Acceptance Criteria
Implementation Notes
This is a documentation-only item. Create a short section (10-20 lines) in the project documentation that establishes the process. The pattern used by many Python projects: (1) add a Deprecation-Warning header to responses from deprecated endpoints, (2) log a deprecation warning server-side, (3) document the deprecation in the CHANGELOG (item 9), (4) remove after one minor version cycle. For pre-1.0, the policy can be simpler: "Breaking changes are documented in the CHANGELOG. Pre-1.0 versions may change APIs in any release." The key deliverable is establishing the process before it is needed.
References
- Eval finding: Test 18 (Evolution Freedom) — part of the "Invisible Contract" compound
- Related files:
README.md, api/workspaces.py, api/search.py, api/export_api.py
Repository: cppa-cursor-browser
Assignee: Brad @bradjin8
Points: 1
Severity: Medium
Problem
The project has no documented API deprecation process. The Flask route handlers lack parameter documentation, and there is no mechanism to warn consumers when endpoints, parameters, or response shapes will change. Combined with the absence of a versioning policy (item 9), consumers of the HTTP API cannot determine the current contract and will receive no warning when it changes. For a tool at version 0.1.0 this is expected, but the production-level deployment documentation creates expectations the versioning posture does not support.
Acceptance Criteria
README.md,CONTRIBUTING.md, ordocs/API_DEPRECATION.md)Deprecationresponse header pattern is defined for future use (e.g.,Deprecation: true; sunset=2026-09-01)Implementation Notes
This is a documentation-only item. Create a short section (10-20 lines) in the project documentation that establishes the process. The pattern used by many Python projects: (1) add a
Deprecation-Warningheader to responses from deprecated endpoints, (2) log a deprecation warning server-side, (3) document the deprecation in the CHANGELOG (item 9), (4) remove after one minor version cycle. For pre-1.0, the policy can be simpler: "Breaking changes are documented in the CHANGELOG. Pre-1.0 versions may change APIs in any release." The key deliverable is establishing the process before it is needed.References
README.md,api/workspaces.py,api/search.py,api/export_api.py