Feature Flag Policy Template (OpenFeature)

Feature Flag Policy: [Organisation or product line]

Standard for using feature flags safely: flag types and their maximum lifetimes, naming and required metadata, lifecycle and expiry, targeting and evaluation context, defaults and failure behaviour, kill switches, change control and audit, testing, observability, security and privacy, and the management of flag debt. Evaluation terms (provider, evaluation context, targeting key, hooks, events, resolution reasons and error codes) follow the OpenFeature specification, release v0.9.0 (July 2026), so the policy stays independent of the flag vendor or in-house service in use. Replace every [bracketed] value and every row marked Example.

Document control

Approvals

Revision history

Contents

1. Purpose, scope and principles
2. Roles and responsibilities
3. Policy statements
4. Flag types and lifetimes
5. Naming and metadata
6. Lifecycle and expiry
7. Evaluation, targeting and rollout
8. Kill switches and operational flags
9. Change control, access and audit
10. Testing
11. Observability
12. Security and privacy
13. Flag debt and cleanup
14. Exceptions
15. Compliance measurement
16. Review cycle
17. Glossary and references

1. Purpose, scope and principles

1.1 Purpose

Feature flags let [Organisation] separate deployment from release, roll out gradually, run experiments and switch off failing functionality without a deploy. The same power creates risk: every flag doubles the number of code paths, a flag change can break production as surely as a bad deploy, and forgotten flags turn into hidden configuration nobody understands. This standard keeps the benefits and limits the risk.

1.2 Scope

In scope: every runtime switch that changes application behaviour for some or all users and is evaluated from a flag platform, a configuration service or an environment-specific rule set, in back-end services, web front ends and mobile apps.

Out of scope: static build-time configuration that requires a redeploy, infrastructure configuration managed as code, and licence enforcement inside commercial products we buy. Runtime configuration values (limits, thresholds) delivered by the same platform follow section 8 when they act as operational controls and the Configuration Reference (docs/configuration-reference) otherwise.

1.3 Principles

• A flag is temporary unless it is explicitly typed as long-lived.
• The default value is the safe value, and the code works when the flag platform is unreachable.
• Flag changes in production are changes: authorised, recorded, observable and reversible.
• Entitlements and security decisions are enforced on the server, never only by a client-side flag.
• Code reads flags through one abstraction (OpenFeature SDK or an in-house wrapper), never by calling a vendor API directly from business logic.

2. Roles and responsibilities

R = responsible, A = accountable, C = consulted, I = informed. The flag owner is a team, not a person, so ownership survives staff changes.

3. Policy statements

4. Flag types and lifetimes

A release flag that has to stay longer than its lifetime is either an unfinished project (extend under section 14) or a disguised permission or operational flag (change its type, owner and review cadence).

5. Naming and metadata

5.1 Naming convention

Format: <team>.<area>.<type-prefix>-<short-description> in lower case, words separated by hyphens, no personal names and no dates.

Keys are never reused. A removed key stays reserved in the platform archive.

5.2 Required metadata

5.3 Flag register extract

FLG-0412 was created on 2026-08-04; 90 days later is 2026-11-02, the expiry shown.

6. Lifecycle and expiry

6.1 States

A flag moves through the states below. Operational and permission flags skip the rollout states and stay LongLived until they are no longer needed; every other type is expected to reach Removed.

6.2 Expiry handling

1. The platform notifies the owning team [14] days before a flag's expiry and again on the day.
2. On expiry the flag appears on the flag debt report (section 13) and the team's dashboard.
3. An extension needs a reason and new date, approved by the engineering manager (first extension) or platform engineering (second and later).
4. A flag expired for more than [30] days blocks new flag creation by the owning team in the same service until resolved, unless an exception is approved.

6.3 Cleanup

• Cleanup window (Example): release and migration flags are removed within 30 days of reaching FullyOn or RolledBack (abandoned); experiment flags within 30 days of the decision.
• Removal is a normal code change: remove the flag check, delete the losing branch and its tests, then archive the flag in the platform after the code is deployed everywhere, including the oldest supported mobile app version.
• Create the cleanup ticket at the same time as the flag, so the work is planned rather than remembered.

7. Evaluation, targeting and rollout

7.1 Evaluation through OpenFeature concepts

• Application code calls the flag evaluation API with a flag key, a typed default value (boolean, string, number or structure) and, where needed, an evaluation context.
• A provider connects the API to the flag platform. Code never depends on a provider directly, so the platform can be replaced.
• The evaluation context carries the targeting key (a stable identifier such as a pseudonymous user ID or tenant ID) and approved attributes (section 12.2).
• Evaluation details include a resolution reason, such as STATIC, DEFAULT, TARGETING_MATCH, SPLIT, CACHED, DISABLED, UNKNOWN, STALE or ERROR, and on failure an error code, such as PROVIDER_NOT_READY, FLAG_NOT_FOUND, PARSE_ERROR, TYPE_MISMATCH, TARGETING_KEY_MISSING, INVALID_CONTEXT, PROVIDER_FATAL or GENERAL. Log and measure these (section 11).
• Hooks run code at the before, after, error and finally stages of an evaluation; use them for telemetry and validation, not for business logic.
• Applications wait for the provider ready event, or use the safe default until it arrives, and handle error and stale events.
• Experiment and rollout metrics MAY be recorded through the OpenFeature tracking API (added in specification v0.9.0), using the same evaluation context as the evaluation, so variants and outcomes such as conversions or errors join cleanly. Tracking events follow the same attribute allow list as the context (section 12.2).

7.2 Failure behaviour

7.3 Targeting and rollout

• Percentage rollouts MUST bucket on the targeting key with consistent hashing so a user keeps the same variant as the percentage grows.
• Use the tenant or account ID as the targeting key when the whole tenant must see one behaviour (B2B features, billing).
• Roll out in stages with guardrail checks between stages.

Experiment flags follow the sample size, duration and stopping rules of their A/B Test Plan (product/ab-test-plan) instead of this staged rollout.

7.4 Flag dependencies

Avoid flags that depend on other flags. Where unavoidable, record the dependency in metadata (section 5.2), evaluate the prerequisite first, and test the allowed combinations. A combination that must never happen is enforced by the platform's prerequisite rules, not by convention.

8. Kill switches and operational flags

• Every external dependency on a Tier 1 user path that can fail independently (third-party scoring, recommendations, non-essential widgets) SHOULD have an operational flag that degrades it gracefully.
• Kill switches are listed in the service runbook (dev/runbook) with the expected effect, the metric that shows it worked and how to restore.
• Kill switches evaluate locally from cached rules, so they work when the flag platform is slow or down. Critical kill switches MAY also have a static configuration fallback.
• During a declared incident the incident commander or on-call SRE may flip a kill switch without second approval; the change is recorded in the incident timeline.

Kill switches are exercised in the Game Day Plan (ops/game-day-plan).

9. Change control, access and audit

9.1 Access

Access is granted through single sign-on groups with least privilege; there are no shared accounts. Platform API tokens used by automation are scoped to one project and environment and rotated.

9.2 Change records

• The platform audit log records who changed which flag, what changed, when, and the change note, and is retained for at least [1 year] (Example; align with the security logging standard).
• Flag changes are exported to the observability stack as change events, so dashboards show them next to deployments.
• A flag change that alters behaviour for all users of a Tier 1 service is a standard change under Change Request (ops/change-request), pre-approved by this policy when it follows section 7.3.
• Flags MAY be managed as code (definitions in a repository, applied by a pipeline). When they are, the repository review replaces platform approval, and emergency changes in the platform are reconciled back to code within one business day.

9.3 Freeze periods

During change freezes (for example peak trading days), only kill switches and rollbacks are allowed on Tier 1 flags.

10. Testing

• Unit and integration tests cover both values of a boolean flag and every variant of a multivariate flag that can reach production.
• At least one end-to-end suite runs with all flags at their default values, which is what users get when the platform fails.
• Tests set flags through an in-memory test provider or the SDK's testing utilities, never against the shared production platform.
• When two flags interact, test the combinations that production rules allow; document disallowed combinations as prerequisites (section 7.4).
• Removing a flag removes its tests for the deleted path in the same change.

11. Observability

The OpenTelemetry semantic conventions for feature flag evaluations are at Development status as of October 2026; use them for attribute names where your stack supports them and check the current status at opentelemetry.io. Do not record the full evaluation context; record the flag key, variant and reason.

12. Security and privacy

12.1 Security rules

• Client-side SDKs receive only the flags and evaluated values that client needs; flag keys and descriptions visible to clients must not reveal confidential plans.
• Permission flags gate UI only on clients; the server enforces the entitlement on every request (FF-07).
• Flags never hold secrets (FF-08); secrets come from the secrets manager.
• The flag platform is a production control plane: protect it with SSO, multi-factor authentication, least privilege and audit, and include it in threat models of the services that depend on it (Threat Model, security/threat-model).
• Client-side flag payloads are treated as user-controllable: a user can change what their client evaluates, so never rely on a client flag for a security decision.

12.2 Evaluation context attributes

New attributes need privacy approval (FF-06). Where the platform is a third-party service, the vendor is a processor and the data processing agreement and transfer basis must cover the attributes sent.

13. Flag debt and cleanup

The platform team publishes a monthly flag debt report per team: expired flags, flags fully rolled out but not removed, flags with zero evaluations for 30 days, and flags without an owning team. Teams plan cleanup in the next iteration; the engineering manager reviews it in the monthly operational review.

Worked example (Example): Corvid's checkout team owns 46 flags. Of these, 30 are release or experiment flags and 16 are long-lived. Seven release or experiment flags are past expiry, so the expired ratio is 7 / 30 x 100 = 23.3%, above the 10% target in section 15. The team schedules removal of FLG-0377 and the six other expired flags in the next iteration and blocks new release flags in the checkout service until the ratio is below target.

Flag debt that cannot be removed quickly because of old mobile app versions is recorded in the Technical Debt Register (architecture/tech-debt-register) with the minimum app version that will allow removal.

14. Exceptions

An exception names the statement (section 3), the flag or service, the reason, compensating controls, approver and expiry, at most [6] months ahead.

15. Compliance measurement

Incidents linked to flag changes are analysed with the Postmortem template (dev/postmortem).

16. Review cycle

• Scheduled review every 12 months by the policy owner with SRE, AppSec, product and privacy.
• Early review after: an incident caused by a flag change or a stale flag; a change of flag platform or SDK abstraction; a new OpenFeature specification release that changes stable sections used here; a new class of client (for example a new mobile platform).
• Review outcomes are recorded in the revision history.

17. Glossary and references

17.1 Glossary

17.2 References

Standard and licence note

Based on the OpenFeature specification, release v0.9.0 (July 2026), a Cloud Native Computing Foundation project; the specification repository is licensed under Apache-2.0 and the openfeature.dev documentation under CC BY 4.0. Concept, type, reason and error-code names are cited from OpenFeature with attribution; the explanations are original and no specification text is reproduced. OpenTelemetry is cited by name for the status of its feature flag conventions. The feature toggle categories reflect common industry practice; the article by Pete Hodgson is cited as background only. Check the current OpenFeature specification and the status of each section at openfeature.dev before relying on this standard. Vendor flag platforms are trademarks of their owners; this template is not affiliated with or endorsed by them. Original text written for this collection. Template licence: MIT.