THE GITHTML FIELD GUIDE
Feature flag lifecycle template from introduction to removal
A feature flag document should explain the behavior it controls and the conditions for enabling, disabling, and removing it. Identify the owner, supported states, dependencies, and evidence required for each transition. Include a retirement plan at creation time so a temporary rollout mechanism does not become an unexplained permanent branch.
Describe behavior rather than the flag name
A short identifier does not explain what changes when the flag is evaluated. State the user-visible difference, where evaluation occurs, and which environments or audiences are in scope. An illustrative preview flag might show a new export confirmation screen without changing the underlying export format. That distinction matters when someone tries to mitigate a backend issue by toggling the interface. Record prerequisites and related controls so an operator does not assume every combination has been tested. Avoid putting secret targeting data or customer lists in the documentation.
Specify transitions with evidence
Create a state record for off, limited exposure, broadly enabled, and retired when those stages fit the project. For each transition, name the decision owner and the evidence required. Google's canary-release material is useful background for evaluating limited exposure, but your team's criteria must reflect its workload and risks. An illustrative check might compare failed confirmation attempts between the supported paths; it is not a universal metric prescription. Explain how the team will observe unexpected behavior and where an authorized responder can find the recovery procedure.
- Purpose: identify the behavior and the reason for temporary control.
- Dependencies: list incompatible states and required configuration.
- Retirement: name the removal owner and the evidence that the old path is unnecessary.
Account for cleanup and historical readers
Removing the control may require deleting old code, tests, configuration, dashboards, and documentation. Track those tasks explicitly rather than equating full exposure with retirement. Preserve enough history to explain older deployments without leaving obsolete operating instructions looking current. Put lifecycle status and last verification date at the beginning of the HTML page. If a reviewer is reading a saved snapshot on a phone, they should immediately see whether it describes a proposal, an active rollout, or a flag that has already been removed.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.