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