add-compat-flag

## Adding a Compatibility Flag Compatibility flags control behavioral changes in workerd. They allow breaking changes to be rolled out gradually using compatibility dates. Follow these steps in order. ### Step 1: Choose flag names Every flag needs: - **Enable flag**: Opts in to the new behavior (e.g., `text_decoder_replace_surrogates`) - **Disable flag**: Opts out after it becomes default (e.g., `disable_text_decoder_replace_surrogates`). Only needed if the flag will eventually become default for all workers. Naming conventions: - Use `snake_case` - Enable flag describes the new behavior positively - Disable flag uses a `no_` or `disable_` prefix, or describes the old behavior ### Step 2: Add to `compatibility-date.capnp` Edit `src/workerd/io/compatibility-date.capnp`. Add a new field at the end of the `CompatibilityFlags` struct. ```capnp myNewBehavior @<NEXT_ORDINAL> :Bool $compatEnableFlag("my_new_behavior") $compatDisableFlag("no_my_new_behavior") $compatEnableDate("2026-03-15"); # Description of what this flag changes and why. # Include context about the old behavior and what the new behavior fixes. ``` Replace `<NEXT_ORDINAL>` with the value returned by the `next-capnp-ordinal` tool. Key points: - The field number must be the next sequential ordinal. **Use the `next-capnp-ordinal` tool** to find it: call it with `file: "src/workerd/io/compatibility-date.capnp"` and `struct: "CompatibilityFlags"`. Do NOT guess or hardcode the number. - The field name is `camelCase` and becomes the C++ getter name (e.g., `getMyNewBehavior()`). - `$compatEnableDate` is the date after which new workers get this behavior by default. Set this to a future date. If the flag is not yet ready for a default date, omit `$compatEnableDate` — the flag will only activate when explicitly listed in `compatibilityFlags`. - Add `$experimental` annotation if the feature is experimental and should require `--experimental` to use. - The comment block is required and serves as internal documentation. Available annotations: | Annotation | Purpose | |---|---| | `$compatEnableFlag("name")` | Flag name to enable the behavior | | `$compatDisableFlag("name")` | Flag name to disable after it's default | | `$compatEnableDate("YYYY-MM-DD")` | Date after which behavior is default | | `$compatEnableAllDates` | Force-enable for all dates (rare, breaks back-compat) | | `$experimental` | Requires `--experimental` flag to use | | `$neededByFl` | Must be propagated to Cloudflare's FL proxy layer | | `$impliedByAfterDate(name = "otherFlag", date = "YYYY-MM-DD")` | Implied by another flag after a date | ### Step 3: Use the flag in C++ code Access the flag via the auto-generated getter: ```cpp // In code that has access to jsg::Lock: if (FeatureFlags::get(js).getMyNewBehavior()) { // New behavior } else { // Old behavior } ``` The `FeatureFlags` class is defined in `src/workerd/io/features.h`. The getter name is derived from the capnp field name with a `get` prefix and the first letter capitalized. For JSG API classes, you can also access flags in `JSG_RESOURCE_TYPE`: ```cpp JSG_RESOURCE_TYPE(MyApi, workerd::CompatibilityFlags::Reader flags) { if (flags.getMyNewBehavior()) { JSG_METHOD(newMethod); } } ``` ### Step 4: Add tests Test both the old and new behavior. The test variant system helps: - **`test-name@`** runs with the oldest compat date (2000-01-01) — tests old behavior - **`test-name@all-compat-flags`** runs with the newest compat date (2999-12-31) — tests new behavior In your `.wd-test` file, you can explicitly set the flag: ```capnp const unitTests :Workerd.Config = ( services = [( name = "my-test", worker = ( modules = [(name = "worker", esModule = embed "my-test.js")], compatibilityFlags = ["my_new_behavior"], ), )], ); ``` For tests, the `compatibilityDate` field should not be included. Write test cases that verify both behaviors. Consider edge cases where the flag changes observable behavior. ### Step 5: Document the flag **This is required before the enable date.** 1. Create a PR in the [cloudflare-docs](https://github.com/cloudflare/cloudflare-docs) repository. 2. Add a markdown file under `src/content/compatibility-flags/` describing: - What the flag does - When it becomes default - How to opt in or opt out - Migration guidance if applicable See `docs/api-updates.md` for more details on the documentation process. ### Step 6: Build and verify ```bash # Build to verify the capnp schema compiles just build # Run the specific test just stream-test //src/workerd/api/tests:my-test@ # Run with all compat flags to test the new behavior just stream-test //src/workerd/api/tests:my-test@all-compat-flags # Run the compatibility-date test to verify flag registration just stream-test //src/workerd/io:compatibility-date-test@ ``` ### Checklist - [ ] Flag added to `compatibility-date.capnp` with correct sequential field number - [ ] Enable and disable flag names follow naming conventions - [ ] Comment block describes old behavior, new behavior, and rationale - [ ] Enable date is set (or intentionally omitted for experimental/unreleased flags) - [ ] C++ code uses `FeatureFlags::get(js).getMyNewBehavior()` to branch on the flag - [ ] Tests cover both old and new behavior - [ ] Documentation PR created in cloudflare-docs (required before enable date) - [ ] `compatibility-date-test` passes --- > Source: [cloudflare/workerd](https://github.com/cloudflare/workerd) — distributed by [TomeVault](https://tomevault.io). <!-- tomevault:4.0:skill_md:2026-07-20 -->