From 59265f78b6b43dacd83430930785040275f35849 Mon Sep 17 00:00:00 2001 From: Tudor Date: Wed, 26 Aug 2026 20:11:45 +0100 Subject: [PATCH] docs(flags): Unleash does not create flags by itself MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The runbook said a flag 'appears in the Unleash UI after the backend has evaluated it once'. That is wrong. SDKs read definitions from the server and never register anything, and metrics for an unknown flag are discarded — so a declared flag is evaluated on every request, stays False forever, and never shows up until someone creates it by hand. Found the way these things usually are: staging had been running the flag code for a while and the UI was still empty. Also names the environment trap while here — each stack's token is scoped to one environment, so toggling the other does nothing visible and looks like the flag is broken. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_015mWQnpye9F299NVRCCSRvj --- docs/DEPLOY.md | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/docs/DEPLOY.md b/docs/DEPLOY.md index 14b6f83..7397c96 100644 --- a/docs/DEPLOY.md +++ b/docs/DEPLOY.md @@ -176,11 +176,30 @@ registry is orphaned and nothing reads it. variable, and set `UNLEASH_URL` to `http://:4242/api`. 5. Redeploy the application stacks. +### Adding a flag to Unleash + +**Unleash does not create flags by itself.** The SDK reads definitions from the +server and never registers anything, and metrics for a flag the server has +never heard of are discarded. So a flag declared in `backend/flags.py` will be +evaluated on every request, stay `False` forever, and never appear in the UI +until someone creates it there by hand. + +For each flag in the registry, create one in Unleash with: + +- **Name** — character for character what `backend/flags.py` declares. + snake_case, no hyphens or spaces. A typo produces a flag that looks correct + in the UI and is read by nothing. +- **Type** — Release. No strategies, constraints or variants: these are plain + on/off switches, by design. + ### Turning a feature on -Toggle the flag in the environment you want. Flags appear in the Unleash UI -after the backend has evaluated them once, so a newly declared flag shows up -shortly after the deploy that introduced it. +Toggle the flag in the environment matching the stack you mean: **development** +for staging, **production** for prod. The token in each stack is scoped to one +environment, so toggling the other one has no visible effect. + +The SDK refreshes every 15 seconds, so the API reflects the change almost at +once; the pages follow on their own schedule, below. A flip reaches school pages within about five minutes and place pages within the hour. Next's ISR does the propagating — it revalidates a route at the -- 2.54.0