Skip to content

docs: add compatibility date migration guide to README - #7441

Open
spideydotjs wants to merge 1 commit into
cloudflare:mainfrom
spideydotjs:docs/compatibility-date-migration-guide
Open

spideydotjs wants to merge 1 commit into
cloudflare:mainfrom
spideydotjs:docs/compatibility-date-migration-guide

Conversation

@spideydotjs

Copy link
Copy Markdown

Fixes #7282

Overview

Addresses #7282 by providing a clear, step-by-step compatibility date migration guide in README.md.

What is covered

  1. How to check current compatibility dates across workerd.capnp configs, wrangler.toml/jsonc, and .wd-test files.
  2. How to plan date upgrades using compatibility-date.capnp, test individual feature flags early, or opt out of specific behavior changes using no_ prefix flags.
  3. How to test upgraded dates locally via workerd serve and test suite matrix targets (@all-compat-flags).

Add a dedicated guide in README.md explaining how compatibility dates
operate in workerd, addressing issue cloudflare#7282.

The guide covers:
1. Locating current compatibility dates in workerd.capnp, wrangler
configurations, and .wd-test suites.
2. Reviewing flag enable dates in compatibility-date.capnp, adopting
flags incrementally, and opting out via no_ prefix flags.
3. Testing compatibility dates locally with workerd serve and test
suite variants (@all-compat-flags).

Fixes cloudflare#7282
@spideydotjs
spideydotjs requested review from a team as code owners September 20, 2026 08:29
@github-actions

github-actions Bot commented Sep 20, 2026

Copy link
Copy Markdown

All contributors have signed the CLA ✍️ ✅
Posted by the CLA Assistant Lite bot.

@spideydotjs

Copy link
Copy Markdown
Author

I have read the CLA Document and I hereby sign the CLA

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.

docs: suggest adding compatibility date migration guide to README

1 participant