feature-flag-discipline

Feature Flag Discipline

Core Principle

Feature flags are a deployment tool, not a permanent branching mechanism. Every flag must have an expiration date, an owner, and a cleanup plan. A flag at 100% for more than 30 days is tech debt, not a feature flag.

---

1. Flag Types and Lifecycle

Flag Type	Purpose	Lifespan	Example
Release flag	Decouple deployment from release	Days to weeks	enable_new_checkout_flow
Experiment flag	A/B testing	Weeks (until statistically significant)	experiment_pricing_page_v2
Ops flag	Kill switch for operational control	Permanent (but rarely toggled)	enable_recommendation_engine
Permission flag	User entitlements and access	Permanent (managed by product)	enable_enterprise_sso

Only ops flags and permission flags are allowed to live permanently. Release flags and experiment flags must be removed after rollout or experiment completion.

---

2. Flag Registration -- Required Metadata

Every flag must be registered with the following metadata at creation time:

interface FeatureFlag {
  key: string;                    // e.g., "enable_new_checkout_flow"
  type: 'release' | 'experiment' | 'ops' | 'permission';
  owner: string;                  // Team or individual responsible
  description: string;            // What this flag controls
  createdAt: string;              // ISO date
  expiresAt: string;              // ISO date -- REQUIRED for release and experiment flags
  jiraTicket: string;             // Cleanup ticket created at flag creation time
  defaultValue: boolean;          // What happens if the flag system is down
  killSwitchSafe: boolean;        // Can this be turned off instantly without data loss?
}

Example Registration

const flags = {
  enable_new_checkout_flow: {
    key: 'enable_new_checkout_flow',
    type: 'release',
    owner: 'payments-team',
    description: 'Enables the redesigned checkout flow with Apple Pay support',
    createdAt: '2025-06-01',
    expiresAt: '2025-07-15',
    jiraTicket: 'PAY-1234',
    defaultValue: false,         // If flag system is down, use old checkout
    killSwitchSafe: true,        // Can disable instantly, user retries with old flow
  },
};