Change Management Policy

Status: ACTIVE Owner: Daan ([email protected]) Effective: 2026-04-20 Last reviewed: 2026-04-20 Next review: 2026-10-20

Purpose

Ensure that changes to rotor.sh production systems are reviewed, tested, and deployed in a controlled manner to minimize risk and maintain availability.

Scope

All changes to production infrastructure: code deployments (apps/api, apps/worker, apps/www), database migrations, Railway/Fly configuration changes, and infrastructure-as-code changes.

Policy

1. Pull Request Review

All code changes require at least one approving review from a Rotor team member before merge. Self-approval is prohibited except for hotfixes under the emergency procedure below.

2. CI Gates (must pass before merge)

The following CI checks must pass on every PR:

  • pnpm typecheck — TypeScript compilation across all packages
  • pnpm test — full unit test suite (≥95% pass rate; flaky tests are fixed within 24h)
  • bash scripts/audit-prefix.sh — BullMQ prefix isolation invariant
  • bash scripts/audit-compliance-docs.sh — no PLACEHOLDER compliance docs
  • bash scripts/audit-openapi.sh — all /v1/ routes documented

3. Deploy Cadence

  • Staging: automatic deploy on merge to main via Railway CI
  • Production: manual promotion from staging after smoke tests pass (minimum 30 min soak)
  • Database migrations: applied via pnpm db:migrate before worker/API restart; rollback script required in PR description for all DDL changes

4. Feature Flags

New features that affect billing, quotas, or enterprise behavior must be gated behind a feature flag in the feature_flags table. This allows instant rollback without a code deployment.

5. Emergency Hotfix Procedure

For critical production incidents (data loss, auth bypass, billing error):

  1. Create a hotfix branch directly from the last production tag.
  2. Implement the minimal fix; add a regression test.
  3. Get async review from at least one team member (Slack DM acceptable for P0).
  4. Deploy directly to production; backfill the PR review within 2 business days.
  5. File an incident report within 24 hours.

6. Secrets and Environment Variables

Environment variable changes (Railway vault) must be:

  • Documented in the PR description with the variable name (not value).
  • Applied in staging first, then production.
  • Never committed to version control.

Review Cadence

Reviewed annually. Next review: 2026-10-20.