get to prod tasks

tasks/web-production/28-api-versioning.md

@@ -0,0 +1,73 @@
+# 28. API Versioning & Deprecation Strategy
+
+meta:
+  id: web-production-28
+  feature: web-production
+  priority: P2
+  depends_on: []
+  tags: [api, stability, mobile]
+
+objective:
+- Establish API versioning and deprecation strategy to support mobile app updates without breaking existing clients
+
+deliverables:
+- API versioning scheme
+- Deprecation policy documentation
+- Backward compatibility testing
+- Mobile client version tracking
+
+steps:
+1. Implement API versioning:
+   - Current: tRPC v10 (consider upgrade to v11)
+   - Add version header or URL prefix for breaking changes
+   - Version format: v1, v2, etc.
+   - Mobile apps send X-API-Version header
+2. Create deprecation policy:
+   - Document in docs/API_VERSIONING.md
+   - Breaking changes only in major versions
+   - Support previous version for minimum 6 months
+   - Announce deprecations 3 months in advance
+   - Sunset dates for old versions
+3. Add version negotiation:
+   - Backend supports multiple tRPC router versions
+   - Route to correct router based on version header
+   - Default to latest for web clients
+4. Track client versions:
+   - Log app version from User-Agent or X-Client-Version
+   - Dashboard showing active client versions
+   - Alert when old versions still in use near sunset
+5. Add compatibility tests:
+   - Test all mobile app versions against current API
+   - Automated compatibility matrix
+   - Breaking change detection in CI
+6. Document API changes:
+   - Changelog for all API modifications
+   - Migration guides for major versions
+   - Breaking vs non-breaking classification
+
+tests:
+- Unit: Test version routing
+- Integration: Test old client with new API
+- Compatibility: Verify mobile app versions work
+
+acceptance_criteria:
+- API versioning scheme documented and implemented
+- Mobile apps send version header in all requests
+- Backend supports at least 2 API versions simultaneously
+- Deprecation policy published and followed
+- 6-month support window for old versions
+- Client version tracking dashboard active
+- Compatibility tests passing for all supported versions
+- Changelog maintained for all API changes
+
+validation:
+- Mobile app sends X-API-Version: 1 → receives v1 responses
+- Deploy v2 changes → v1 clients continue working
+- Check dashboard → active client versions visible
+- Review changelog → all changes documented
+
+notes:
+- tRPC v10 to v11 is a breaking change — plan migration carefully
+- Mobile apps may take weeks to update — long support windows needed
+- Consider using feature flags instead of versioning for minor changes
+- Track iOS and Android app versions separately