Feature flag release notes: what to say, and when
5 min read
Closing the loop on a feature request assumes a clean moment when the thing shipped. A feature flag removes that moment, which is what makes feature flag release notes hard to time. The code merges, the flag exists, and for days or weeks afterward the feature is simultaneously live in production and invisible to almost everyone who might want it, including, often, the person who originally asked for it. Tell them too early and they hit a feature that isn’t there yet. Tell them too late and the loop that was supposed to build trust instead reads as forgotten.
Why does a flag break the usual “ship it, tell them” sequence?
Because it splits one event into at least two: the code becoming live, and the flag being turned on for a given account. Every process for closing a feedback loop assumes those happen together, which is true for most releases and false for anything gated behind a flag used for staged rollout, targeting, or a kill switch. Closing the customer feedback loop describes telling the requester the moment a changelog entry is approved and published; that step is written for the case where publishing the entry and the feature being usable are the same moment, and a flag is exactly the case where they are not.
| Moment | What’s true | Should the requester be told yet |
|---|---|---|
| Code merged, flag off everywhere | Feature exists, nobody can use it | No |
| Flag on for the requester’s account | Feature exists, they specifically can use it | Yes |
| Flag on for a rollout percentage that excludes them | Feature exists, they still cannot use it | No |
| Flag fully removed, feature is just on | Feature exists for everyone | Yes, if not told already |
What’s the actual rule for when to tell someone?
Tell them when the flag is on for their account, not when the code merges and not when the flag is created. That single rule handles every row in the table above, because it ties the notification to the one fact that actually matters to the requester: can they, right now, go use the thing. A notification tied to the merge or the flag’s creation is really a notification about engineering progress, and a requester who asked for a feature does not want a progress report, they want to know when to go look.
Does that mean the requester needs early or special access?
Not necessarily, and forcing it creates its own problem. If the flag is being rolled out gradually for load or stability reasons, moving one account to the front of the queue just to close a loop faster undermines the reason the rollout is staged in the first place. The honest options are: wait until the requester’s account reaches the rollout naturally and tell them then, or, if the ask is time-sensitive enough to justify it, deliberately flag them in early as a real decision made by whoever owns the rollout, not as a side effect of wanting to send a notification.
What if the flag is a kill switch, not a rollout mechanism?
Then the safe assumption flips. A flag used to be able to quickly disable a feature, rather than to stage its release, usually means the feature is meant to be fully live once the flag is created, and the flag exists for safety rather than sequencing. In that case, telling the requester at deploy time is correct, the same as any unflagged release; the flag’s presence is an operational detail that shouldn’t change when the loop closes. The distinction that matters is what the flag is for, not whether one exists.
Does the flag change what feature flag release notes should say?
It changes when the entry publishes, not what it contains. An entry published the moment the flag is on for 100% of accounts reads exactly like a normal changelog entry, and should; a reader finding it later has no reason to know a flag was ever involved. What it should not do is publish while the flag is only on for a small rollout percentage, because a public changelog entry sends everyone who reads it, including accounts without the flag, to go look for a feature they cannot find, which is a worse version of the same problem, at product-wide scale instead of one requester’s scale. That timing rule is the whole difference between feature flag release notes and an ordinary entry: the content is the same, only the publish date moves. How to write release notes covers the “no action needed” discipline that applies here too: readers need to be told this applies to them, not just that it exists somewhere.
Should product-update emails treat a flagged feature differently?
Yes, and mostly by delaying rather than rewriting. The product update email template covers targeted notifications versus broad digests; a flagged feature is a case where a targeted notification’s timing has to be checked against the recipient’s own flag state before it sends, something a broad digest can’t easily do at all, which is one more reason a digest is the wrong channel for anything still mid-rollout.
FAQ
Should you tell a requester their feature is “coming soon” once the flag exists but isn’t on for them? Only if there’s a real, near-term date attached, and even then sparingly. A “coming soon” with no date reads the same as silence after enough time passes, and it creates a second promise that also has to be tracked and honored.
Who decides when a flag is far enough along to close the loop? Whoever owns the rollout, not whoever owns the notification. The rollout owner knows whether “100% of accounts” is imminent or still weeks out; tying the loop-closing step to their state, rather than to a fixed calendar date, keeps the notification honest.
Does a feature behind a permanent flag (never fully removed) ever get a public changelog entry? Yes, once it reaches whatever “generally available” means for that product, even if the flag itself stays in the codebase forever for operational reasons. The changelog entry is about availability to the reader, not about the implementation detail of how that availability is implemented.
What if the flag gets removed and the feature is killed instead of shipped? That is a decline, not a shipped notification, and it deserves the same care as any other decline. How to decline a feature request covers what that message should say; closing the loop honestly sometimes means closing it with a no.
Do feature flag release notes need a separate template from a normal entry? No template change, only a gating step before publish: check the flag state for the account that asked, not just that the code merged, and hold the entry until that check passes. Everything else about the entry, the wording, the length, the FAQ discipline, stays the same as any other release note.
The technical claims in this article have not been independently reviewed. If something here is wrong, tell us and we will correct it.