As the lead for a team running dozens of Cloudflare Workers, what rule would you set for bumping compatibility dates, and why?
answer
- surprise versus drift
- bumps as their own change
- flags history diff in review
- a maximum age per Worker
- disable flags as tracked debt
basics
~20 sBump on a regular cadence, in a change of its own that lists the flags dated in the window, tested and rolled out gradually at the new date. Set a maximum age, track every disable flag as debt, and decide the Node.js default deliberately.
solid answer
~40 sNever bumping avoids surprises but loses date-gated features and security fixes and builds up one huge, risky jump; always taking the newest date ships unreviewed runtime changes inside feature deploys. I would start new Workers at today's date, bump existing ones quarterly in a dedicated change that lists the flags dated in the window, run the test suite and `wrangler dev` at the new date, and roll it out gradually with a named rollback owner. A CI check enforces a maximum age, held-back changes get a disable flag with an owner and a removal trigger, and the team decides once whether Workers accept the Node.js compatibility default from 2026-08-04 or opt out with both disable flags.
go deeper
Recall that each Worker has its own compatibility date and that moving it changes runtime behaviour at the next deploy.
Explain how a bump turns on every change dated in the window, and how disable flags and tests at the new date contain it.
Show how you would ship a bump safely: a dedicated change, the flags history diff, tests at the new date and a gradual rollout.
Own the trade-off between surprise and drift: set the cadence, the maximum age, who bumps, how disable flags are retired, and the Node.js stance.
## Why this is a lead's decision Every Cloudflare Worker carries its own `compatibility_date`. Across dozens of Workers, the dates drift apart: the one created last month runs current semantics, the one nobody has touched since 2023 runs 2023 semantics. Each date is safe on its own, because the runtime supports old dates indefinitely. The cost shows up elsewhere, and a lead decides where the team pays it. ## The two extremes and what they cost | Policy | What it buys | What it costs | |---|---|---| | Never bump | No surprise behaviour changes | Features gated on a current date are unavailable; documentation describes current behaviour, so engineers must read the flags history for every API; the eventual forced bump carries years of changes at once | | Always newest (`wrangler deploy --latest`, or today's date on every deploy) | Always current, small diffs | Runtime changes ship unreviewed inside unrelated feature deploys, and a regression cannot be told apart from the feature | The middle ground is the real decision: how often, by whom, and with what evidence. ## A policy that holds up 1. **New Workers start at today's date**, with no redundant flags. From 2026-08-04 this includes Node.js compatibility by default, so a new Worker either accepts it or opts out explicitly with `no_nodejs_compat` and `no_nodejs_compat_v2`. 2. **Bumps are their own change.** A date bump never rides with a feature; the pull request lists the flags whose dates fall in the window, taken from the compatibility flags history, and says which ones the code touches. 3. **A cadence with a floor.** For example, every Worker is bumped quarterly and none may fall more than a year behind; a CI check reading `compatibility_date` from each Wrangler file enforces it. Small, regular jumps keep each review short. 4. **Tests run at the new date.** The test suite runs inside the Workers runtime with the Worker's own date and flags, and `wrangler dev` reproduces the same runtime locally, so the bump is exercised before deploy. Production-only behaviours still need a staged rollout. 5. **Gradual rollout.** Each Worker version carries its own date, so a bump can go to a small share of traffic first with a quick rollback; who owns that rollback is part of the policy. 6. **Held-back changes are tracked debt.** A disable flag such as `retain_authorization_on_cross_origin_redirect` or `no_nodejs_global_timers` lets a Worker take everything except one change. Each one gets an owner and a removal trigger, otherwise the configuration slowly becomes a list of exceptions nobody understands. ## What a bump change contains A reviewer should be able to approve a bump from the change itself: - the old and new dates, and the list of gated changes whose dates fall between them; - for each change the code could touch, the call sites checked and the result; - any disable flag added, with its owner and the condition for removing it; - the test run at the new date and the rollout plan, including the first traffic share and who watches it. ## Points that need judgment - **Shared code across Workers.** A library used by several Workers runs under several dates. Either the library avoids date-sensitive behaviour, or the team keeps Workers that share it within a narrow date band. - **Node.js compatibility as a platform rule.** With the default flipped on 2026-08-04, bumping past it turns on Node.js APIs and v2 polyfills that grow the bundle, and population of `process.env` from secrets. Some teams accept the default everywhere for npm reach; others require explicit opt-out for Workers that do not need it, to keep the bundle small and secrets away from dependencies that read `process.env`. - **Ownership at scale.** A platform team can bump all Workers centrally with a scripted diff, or each service team bumps its own. Central bumps keep the fleet aligned but put runtime changes into code the platform team does not know; delegated bumps need the floor to stop stragglers. - **Security fixes behind dates.** Some gated changes close a real risk, such as stripping `Authorization` on cross-origin redirects. A policy that lets Workers sit on old dates indefinitely leaves those protections off; that alone argues for a maximum age. ## How to judge the answer There is no single right cadence. A good answer names the trade-off between surprise and drift, puts bumps in their own reviewed change, ties them to tests and a staged rollout at the new date, sets a maximum age, tracks disable flags as debt, and takes a deliberate stance on the Node.js default.
- Why is a two-year compatibility date jump riskier than eight quarterly ones covering the same changes?The total set of changes is the same, but a single jump lands all of them in one deploy, so a regression could come from any of dozens of flags and the review list is too long to read carefully. Quarterly bumps keep each diff to a handful of flags, so tests and rollbacks point at a short list of causes.
- When would you let a Worker stay on an old compatibility date on purpose?When it is frozen and due for retirement, or holds behaviour that cannot be changed safely yet. Then record the exception with an owner and a review date, and check the gated changes it misses, especially security-relevant ones such as stripping Authorization on cross-origin redirects, so the risk is accepted knowingly.
- Old compatibility dates stop working, so the policy only needs to react.
- Bumping the date in the same pull request as a feature saves time.
- Always deploying with the newest date removes all compatibility risk.
- Disable flags can stay in the configuration indefinitely with no owner.
- Node.js compatibility needs no team decision because it is default now.
Assumes Cloudflare Workers and Wrangler 4 as of 2026-10-10: Node.js compatibility is on by default from compatibility date 2026-08-04, and wrangler deploy --latest uses the newest date the installed Wrangler supports.