up

ops/devops/ledger/deprecation-policy.yaml

@@ -0,0 +1,61 @@
+# Findings Ledger API Deprecation Policy
+# DEVOPS-LEDGER-OAS-63-001-REL
+
+version: "1.0.0"
+created: "2025-12-14"
+
+policy:
+  # Minimum deprecation notice period
+  notice_period_days: 90
+
+  # Supported API versions
+  supported_versions:
+    - version: "v1"
+      status: "current"
+      sunset_date: null
+    # Future versions will be added here
+
+  # Deprecation workflow
+  workflow:
+    - stage: "announce"
+      description: "Add deprecation notice to API responses and docs"
+      actions:
+        - "Add Sunset header to deprecated endpoints"
+        - "Update OpenAPI spec with deprecation annotations"
+        - "Notify consumers via changelog"
+
+    - stage: "warn"
+      description: "Emit warnings in logs and metrics"
+      duration_days: 30
+      actions:
+        - "Log deprecation warnings"
+        - "Increment deprecation_usage_total metric"
+        - "Send email to registered consumers"
+
+    - stage: "sunset"
+      description: "Remove deprecated endpoints"
+      actions:
+        - "Return 410 Gone for removed endpoints"
+        - "Update SDK to remove deprecated methods"
+        - "Archive endpoint documentation"
+
+  # HTTP headers for deprecation
+  headers:
+    sunset: "Sunset"
+    deprecation: "Deprecation"
+    link: "Link"
+
+  # Metrics to track
+  metrics:
+    - name: "ledger_api_deprecation_usage_total"
+      type: "counter"
+      labels: ["endpoint", "version", "consumer"]
+      description: "Usage count of deprecated endpoints"
+
+    - name: "ledger_api_version_requests_total"
+      type: "counter"
+      labels: ["version"]
+      description: "Requests per API version"
+
+# Current deprecations (none yet)
+deprecations: []