Skip to content

docs: document preboot deploys and forward-compatible migrations - #2962

Merged
mroderick merged 1 commit into
masterfrom
feature/preboot-zero-downtime-deploys
Sep 28, 2026
Merged

mroderick merged 1 commit into
masterfrom
feature/preboot-zero-downtime-deploys

Conversation

@mroderick

Copy link
Copy Markdown
Collaborator

Summary

Production now runs with Heroku preboot, so a deploy no longer restarts all web dynos at once: new dynos boot first, traffic switches to them about 3 minutes after the deploy, and the old dynos shut down then. This PR writes down what that means for the two audiences whose deploy behaviour changes.

  • CONTRIBUTING.md gains a "Deploys and preboot" section for anyone deploying: the ~3 minute switchover, that heroku ps shows only the new dynos during the overlap (old ones keep serving but do not appear in it), heroku ps:stop for a bad dyno, and when to temporarily disable preboot.
  • AGENTS.md gains "Migrations and Heroku preboot": migrations must be forward-compatible because old code serves against the new schema for ~3 minutes after the release phase runs rake db:prepare. It covers expand/contract, ignored_columns before remove_column, two-step renames, the real meaning of safety_assured, and the disable-preboot escape hatch for migrations that cannot be made forward-compatible.

Related: #2949

Validation

  • Preboot was enabled on codebar-production and confirmed with heroku features:info preboot (Enabled: true). Enabling the feature does not restart dynos.
  • Docs-only diff: no test or lint surface.
  • The two claims an adversarial review corrected (heroku ps behaviour and the boot-failure 503 case) were checked against the live Heroku preboot doc.
  • Step 2 of Enable Heroku preboot for zero-downtime deploys聽#2949 (confirm the next deploy's logs show new dynos starting before old ones stop) is pending the next production deploy.

Post-Deploy Monitoring & Validation

No additional operational monitoring required for this diff (documentation only). The underlying production change (preboot) is validated at the next deploy per issue #2949 step 2: logs should show new web dynos starting before old ones stop, and heroku ps will list only the new dynos during the overlap.

Production runs with Heroku preboot (issue #2949): new web dynos boot
before old ones stop, traffic switches about 3 minutes after a deploy,
and the old dynos shut down then.

Document what this means in CONTRIBUTING.md for anyone deploying: the
switchover timing, that heroku ps shows only the new dynos during the
overlap (old ones keep serving but do not appear in it), heroku ps:stop
for a bad dyno, and when to temporarily disable preboot. Note that the
switch is time-driven, so a release whose web dynos crash on boot still
takes traffic and can 503.

Add forward-compatible migration guidance to AGENTS.md because the
release phase (rake db:prepare) migrates before old dynos stop, so old
code serves against the new schema for about 3 minutes: expand first and
contract later, ignored_columns before remove_column, two-step renames,
what safety_assured does and does not mean, and the disable-preboot
escape hatch for migrations that cannot be made forward-compatible.
@mroderick
mroderick force-pushed the feature/preboot-zero-downtime-deploys branch from f271c5f to 62b3663 Compare September 28, 2026 07:52
@mroderick
mroderick marked this pull request as ready for review September 28, 2026 08:00
@mroderick
mroderick merged commit bb766c8 into master Sep 28, 2026
11 checks passed
@mroderick
mroderick deleted the feature/preboot-zero-downtime-deploys branch September 28, 2026 08:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant