# Release management

This document defines **how releases are sequenced and verified** for the modular Laravel monolith (`PROJECT_RULES.md`: `app/Modules`, thin controllers, services/repositories).

---

## Deployment sequencing (default order)

1. **Announce** maintenance or risk window when migrations or queue semantics change materially.
2. **Database migrations** — run in a controlled step **before** or **with** code depending on the strategy below.
3. **Application code** — deploy only after migrations are compatible with **either** old or new code (expand/contract).
4. **Queue workers** — restart or rolling-restart so workers load **new code** and **consistent config**.
5. **Schedulers / cron** — ensure new commands are registered and old commands retired intentionally.
6. **Post-deploy verification** — smoke tests on auth, tenant boundaries, payroll-critical paths, integrations health.

---

## Migration rollout strategy (expand / contract)

**Expand (safe default)**

1. Migration adds new schema (columns/tables/indexes) compatible with **currently deployed** code.
2. Deploy **new code** that can read/write new schema (still tolerates old rows if needed).
3. Backfill data (jobs or controlled commands) if required.
4. Later migration **contracts** (removes old columns) only after telemetry proves unused.

**Contract**

- Never contract in the same release as first consumer deploy unless proven safe.
- Contract migrations require **explicit governance sign-off** and a **rollback-forward plan** (usually another migration, not `down()`).

---

## Rollback strategy

- **Code rollback** without schema rollback is preferred when migrations were **additive only**.
- If a migration **contracts** or **mutates** data, **code rollback alone may be unsafe** — prefer **forward fix** migration.
- **Database restore** is reserved for confirmed corruption or failed contract migration; see `incident-response.md`.

---

## Queue deployment safety

- **Payload compatibility**: Jobs serialized with Eloquent models must survive schema changes or be migrated to DTOs / IDs only.
- **Drain risky queues** before irreversible migrations when job arguments embed deprecated columns.
- **Horizon / worker config**: ensure timeouts and retries align with new long-running tasks.
- **Feature work** that changes job behavior must document **idempotency** and **retry** semantics (`security-review-checklist.md`).

---

## Feature flag rollout process

- Flags that gate **tenant-visible behavior** must be **tenant-aware** and auditable where risk is high (payroll, permissions).
- Rollout stages: **internal → pilot tenant(s) → percentage → general availability**.
- Each stage requires: owner, success metrics, **rollback** (flag off), and **maximum blast radius**.
- Flags are **temporary** — every flag has a **removal date** or ticket to delete branches and dead code.

---

## Release artifacts

Each production release should attach:

- Migration list + risk class (additive / backfill / contract).
- Notable **integration** or **webhook** behavior changes.
- **Ops** commands that may need running (explicitly listed — no “run random artisan” culture).

---

## References

- `docs/governance/schema-evolution.md`
- `docs/governance/incident-response.md`
- `docs/governance/security-review-checklist.md`