docs/release-process.md

Release Process

This document defines the minimum release checklist for Token Cost Guard.

1) Pre-release checks

• Ensure branch is up to date and CI is green.
• Run local checks:
  • npm run lint
  • npm test
  • npm run security:check
  • npm run bench:baseline (optional local smoke baseline)
• Validate operational readiness:
  • GET /api/v1/health
  • GET /api/v1/ops/metrics
  • GET /api/v1/metrics (Prometheus format)
• Trigger benchmark workflow manually if release risk is high:
  • .github/workflows/benchmark.yml

2) Versioning

• Use semantic version tags: vMAJOR.MINOR.PATCH.
• Recommended:
  • PATCH: bug fixes, no API contract break.
  • MINOR: additive features / endpoints.
  • MAJOR: breaking API or behavior changes.

3) Release execution

1. Merge to main.
2. Create annotated tag:
   • git tag -a vX.Y.Z -m "Release vX.Y.Z"
3. Push tag:
   • git push origin vX.Y.Z
4. Wait for .github/workflows/release.yml to finish.
5. Confirm generated artifacts and GitHub Release notes.
6. Confirm benchmark gate passed (if workflow was run).

4) Post-release verification

• Smoke test key endpoints in production/staging:
  • POST /api/v1/optimize
  • GET /api/v1/policies/audit
  • GET /api/v1/alerts
• Check dead-letter backlog:
  • GET /api/v1/alerts/dead-letters
• Confirm alert webhook delivery success trend via metrics.

5) Rollback trigger and action

Trigger rollback if one or more are true:

• sustained 5xx increase,
• major latency regression,
• incorrect policy behavior in production.

Actions:

1. Switch traffic to degraded-safe mode (fast where needed).
2. Trigger POST /api/v1/policies/rollback.
3. Verify health and replay baseline tests.