P6.REV.001 — Deployment has rollback documentation¶

Field	Value
Principle	P6 (Reversibility)
Severity	`warn`
Evidence	`strong`
Stability	`experimental`

What it checks¶

If the repository has deployment artifacts (Dockerfile, docker-compose, Kubernetes manifests, Terraform configs, CI/CD workflows, Procfile, etc.), it must also have rollback/deployment documentation at one of:

RUNBOOK.md / docs/runbook.md
docs/rollback.md
docs/deployment.md / DEPLOYMENT.md
docs/operations.md

Why it matters¶

P6 asks whether every change can be rolled back cheaply. Deployment is the highest-stakes change a codebase undergoes — pushing a bad release to production has immediate user impact. Without rollback documentation, an agent (or on-call engineer) facing a broken deploy has to reverse-engineer the rollback procedure under pressure.

A runbook documents: how to deploy, how to verify, how to roll back, and who to escalate to. This is the minimum viable reversibility for any deployed system.

When to care¶

Care always for any repo that deploys to production.
Care less for repos that deploy only dev/staging environments, or for repos where deployment is fully managed by a platform team. Even then, a one-paragraph docs/deployment.md is cheap insurance.

How to fix¶

Create docs/deployment.md (or RUNBOOK.md) with at minimum:

# Deployment

## How to deploy
1. Merge to main
2. CI builds and pushes Docker image
3. ArgoCD syncs to production

## How to verify
- Check /health endpoint returns 200
- Monitor error rate dashboard for 15 minutes

## How to roll back
1. Revert the merge commit: `git revert HEAD`
2. Push to main — CI will redeploy the previous version
3. Alternatively: `kubectl rollout undo deployment/my-app`

## Escalation
- On-call: #oncall-channel
- Infra team: @infra-team

Suppressing this rule¶

ignore:
  - rule: P6.REV.001
    reason: "Deployment is managed by platform team; runbook lives in their repo"
    expires: 2027-01-01

History¶

0.3.0 — introduced at stability: experimental.