Step-by-step guide for adding a new autogate to workerd for gradual rollout of risky changes, including enum registration, string mapping, usage pattern, and testing.
Autogates enable gradual rollout of risky code changes independent of binary releases. Unlike compatibility flags (which are permanent, date-based behavioral changes), autogates are temporary gates that can be toggled on/off via internal tooling during rollout, then removed once the change is stable.
| Use an autogate when... | Use a compat flag when... |
|---|---|
| Rolling out a risky internal change gradually | Changing user-visible behavior permanently |
| You need a kill switch during rollout | The change is tied to a compatibility date |
| The gate will be removed once stable | Users need to opt in or out explicitly |
Autogates and compat flags are separate mechanisms — an autogate does not become a compat flag.
Edit src/workerd/util/autogate.h. Add a new entry to the enum :
AutogateKeyNumOfKeysenum class AutogateKey {
TEST_WORKERD,
// ... existing gates ...
// Brief description of what this gate controls.
MY_NEW_FEATURE,
NumOfKeys // Reserved for iteration.
};
Naming convention: SCREAMING_SNAKE_CASE for the enum value.
Edit src/workerd/util/autogate.c++. Add a case to the KJ_STRINGIFY switch before the NumOfKeys case: