docs: document preboot deploys and forward-compatible migrations - #2962
Merged
Merged
Conversation
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
force-pushed
the
feature/preboot-zero-downtime-deploys
branch
from
September 28, 2026 07:52
f271c5f to
62b3663
Compare
mroderick
marked this pull request as ready for review
September 28, 2026 08:00
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.mdgains a "Deploys and preboot" section for anyone deploying: the ~3 minute switchover, thatheroku psshows only the new dynos during the overlap (old ones keep serving but do not appear in it),heroku ps:stopfor a bad dyno, and when to temporarily disable preboot.AGENTS.mdgains "Migrations and Heroku preboot": migrations must be forward-compatible because old code serves against the new schema for ~3 minutes after the release phase runsrake db:prepare. It covers expand/contract,ignored_columnsbeforeremove_column, two-step renames, the real meaning ofsafety_assured, and the disable-preboot escape hatch for migrations that cannot be made forward-compatible.Related: #2949
Validation
codebar-productionand confirmed withheroku features:info preboot(Enabled: true). Enabling the feature does not restart dynos.heroku psbehaviour and the boot-failure 503 case) were checked against the live Heroku preboot doc.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 pswill list only the new dynos during the overlap.