58 lines
2.7 KiB
Markdown
58 lines
2.7 KiB
Markdown
# Migration & Rollout Scaffolding
|
||
|
||
This document tracks temporary code paths, feature flags, and kill switches that
|
||
let us roll out risky changes safely. Keep it current so on-call engineers know
|
||
how to disable new behavior without spelunking through the codebase.
|
||
|
||
## How to Use This Document
|
||
|
||
1. **Add an entry** whenever you introduce code that needs a manual cleanup
|
||
window (feature flags, compatibility layers, installers with rollback paths).
|
||
2. **State the kill switch** (environment variable, UI toggle, config file, or
|
||
systemd override) and who owns the rollout.
|
||
3. **Define removal criteria**. Once criteria are met, delete the scaffolding
|
||
and update this file.
|
||
|
||
### Entry Template
|
||
|
||
```
|
||
## <Feature / Migration Name>
|
||
- Introduced: vX.Y.Z (date/commit, if known)
|
||
- Owner: <team/person>
|
||
- Kill switch: how to disable + default state
|
||
- Monitoring: metrics/logs to watch
|
||
- Cleanup criteria: what must be true before removing scaffolding
|
||
- Notes: cross-links to docs or runbooks
|
||
```
|
||
|
||
## Active Scaffolding
|
||
|
||
### Adaptive Polling Scheduler
|
||
- **Introduced**: v4.24.0 (documented in `docs/monitoring/ADAPTIVE_POLLING.md`)
|
||
- **Owner**: Monitoring subsystem (rcourtman)
|
||
- **Kill switch**: Toggle **Settings → System → Monitoring → Adaptive
|
||
Polling**, or set `ADAPTIVE_POLLING_ENABLED=false` before starting Pulse
|
||
(Docker/Kubernetes). Helm users can override `adaptivePollingEnabled: false`.
|
||
- **Monitoring**: `pulse_monitor_poll_queue_depth`,
|
||
`pulse_monitor_poll_staleness_seconds`, and
|
||
`/api/monitoring/scheduler/health` for breaker/dead-letter status.
|
||
- **Cleanup criteria**: Remove flag and legacy scheduler code after three stable
|
||
releases with `queue.depth < 50` during peak hours and no dead-letter growth.
|
||
- **Notes**: Operational guidance lives in
|
||
`docs/operations/ADAPTIVE_POLLING_ROLLOUT.md`.
|
||
|
||
### Automatic Updates Service
|
||
- **Introduced**: commit `f46ff1792` (2025-10-11) added `scripts/pulse-auto-update.sh`
|
||
- **Owner**: Installer/Update subsystem (rcourtman)
|
||
- **Kill switch**: Disable **Settings → System → Updates → Automatic Updates** or
|
||
set `AUTO_UPDATE_ENABLED=false` in `/var/lib/pulse/system.json`. Installers
|
||
accept `--no-auto-update` to force the flag off.
|
||
- **Monitoring**: `journalctl -u pulse-update.service`, UI update history
|
||
(Settings → System → Updates), and webhook notifications tagged with
|
||
`event_id=system.update`.
|
||
- **Cleanup criteria**: Remove legacy opt-out plumbing once the opt-in rate is
|
||
≥90 % across supported installers and we have at least two release cycles with
|
||
zero rollback events triggered by auto-update.
|
||
- **Notes**: Keep release-specific caveats in `docs/RELEASE_NOTES.md`. The
|
||
update scheduler runs only on systemd installs; container builds ignore the
|
||
flag.
|