Feature Flags - Learning Module

Loading content...

0/246

Flag Lifecycle Management

The Graveyard of Forgotten Flags

Every organization that adopts feature flags eventually faces the same haunting question: "What do all these flags actually do, and are any of them still needed?"

The pattern is predictable. Teams create flags for progressive rollouts. The rollout completes. The flag remains—because removing it requires understanding code that was written months ago, by engineers who may have left, during a sprint that's long forgotten. Multiply this by dozens of teams over years, and you have the flag graveyard: thousands of conditionals that nobody understands, nobody dares to touch, and everybody works around.

This is the single most common failure mode of feature flag adoption. The solution isn't to avoid flags—it's to implement rigorous lifecycle management from day one.

What You Will Learn

By the end of this page, you will understand the complete feature flag lifecycle, governance practices that prevent flag sprawl, automation strategies for flag cleanup, and organizational patterns for sustainable flag management. You'll learn how to enjoy the benefits of flags without drowning in their accumulated debt.

The Feature Flag Lifecycle

Every feature flag passes through distinct phases. Understanding these phases—and having explicit processes for each—is the foundation of flag management.

Phase 1: Creation

A flag is born when a team decides they need dynamic control over a code path. Key decisions at creation time:

Flag type classification — Is this release, experiment, ops, or permission?
Owner assignment — Who is responsible for this flag?
Expiration date — When should this flag be removed? (Required for release/experiment flags)
Documentation — What does this flag control? Why was it created?
Success criteria — What conditions indicate the flag is ready for removal?

flag-creation-metadata.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
// Comprehensive flag metadata at creation time
interface FeatureFlagDefinition {
    // Identity
    key: string;                          // "checkout-v2"
    name: string;                         // "Checkout V2 Progressive Rollout"
    description: string;                  // "New checkout experience with..."
    
    // Classification
    type: "release" | "experiment" | "ops" | "permission";
    
    // Ownership
    owner: string;                        // Team or individual email
    createdBy: string;                    // Creator's email
    createdAt: Date;
    
    // Lifecycle
    expectedRemovalDate: Date;            // When flag should be deleted
    status: "draft" | "active" | "complete" | "stale" | "archived";
    
    // Documentation
    jiraTicket?: string;                  // Link to feature work
    successCriteria?: string;             // "100% rollout with <0.1% error rate"
    removalInstructions?: string;         // How to safely remove
    
    // Targeting
    environments: string[];               // ["staging", "production"]
    defaultValue: any;
    rules: TargetingRule[];
    
    // Analytics
    trackExposure: boolean;               // Log who sees which variant
    tags: string[];                       // ["checkout", "payments", "q1-2024"]
}
 
// Mandatory fields enforced by flag creation API
function createFlag(definition: FeatureFlagDefinition): void {
    // Validate required lifecycle fields for release flags
    if (definition.type === "release" || definition.type === "experiment") {
        if (!definition.expectedRemovalDate) {
            throw new Error("Release and experiment flags require an expected removal date");
        }
        if (!definition.owner) {
            throw new Error("All flags require an owner");
        }
    }
    
    // Set sensible defaults
    definition.status = "draft";
    definition.createdAt = new Date();
    
    // Create in flag store
    flagStore.create(definition);
    
    // Emit creation event for auditing
    auditLog.logFlagCreation(definition);
}

Phase 2: Rollout (Active Use)

The flag is actively used to control feature exposure. During this phase:

Progressive rollout — Gradually increase exposure (1% → 10% → 50% → 100%)
Monitoring — Watch for errors, performance degradation, user feedback
Adjustment — Modify targeting rules based on observations
Documentation updates — Record learnings and decisions

Phase 3: Completion (Flag Served Its Purpose)

The flag has achieved its goal—full rollout, experiment concluded, or capability no longer needed. This is the critical inflection point. The flag's useful life is over, but it still exists in code.

Red flag: If a flag stays in the "complete" state for more than 2 weeks, it's accumulating debt.

Phase 4: Cleanup (Code Removal)

The flag is removed from the codebase:

Flag evaluation removed — Delete the if/else checks
Dead code removed — Delete the code path that's no longer used
Tests updated — Remove flag-related test variations
Flag definition deleted — Remove from flag management system
Documentation archived — Preserve learnings for future reference

Feature Flag Lifecycle Phases
Phase	Duration	Key Activities	Exit Criteria
Creation	Hours	Define metadata, set targeting, assign owner	Flag approved and merged
Rollout	Days to weeks	Progressive exposure, monitoring, adjustment	Target exposure reached
Completion	< 1 week	Mark as complete, plan cleanup	Cleanup PR created
Cleanup	1-2 sprints	Remove code, update tests, delete flag	No references remain

Flag Governance Policies

Without explicit policies, flag management becomes ad-hoc and inconsistent. Effective governance requires policies that are enforced, not just documented.

Essential Governance Policies

•Mandatory expiration dates — Release and experiment flags MUST have an expected removal date at creation. Ops and permission flags may be exempt.
•Owner accountability — Every flag has an owner (team or individual). If the owner leaves, ownership must be explicitly transferred.
•Maximum flag age — Release flags older than 90 days trigger automatic escalation. Experiments older than 60 days are flagged for review.
•Flag budget per service — Each service has a maximum number of active release/experiment flags (e.g., 20). Creating a new flag when at capacity requires removing an old one first.
•Cleanup SLA — Completed flags must be removed within 2 sprints. Violations appear in team health dashboards.
•Approval workflow — Changes to production flags require approval (peer review, QE sign-off, or automated checks).

Policy Enforcement Mechanisms

Policies without enforcement are wishful thinking. Here are enforcement mechanisms that actually work:

flag-policy-enforcement.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
// Enforcement mechanisms for flag governance
 
// 1. CI/CD blocking on stale flags
async function checkFlagHealth(deploymentPipeline: Pipeline): Promise<void> {
    const staleFlags = await flagStore.getStaleFlags({
        service: deploymentPipeline.serviceName,
        olderThan: days(90),
    });
    
    if (staleFlags.length > 0) {
        // Block deployment until flags are addressed
        throw new DeploymentBlockedError(`
            Deployment blocked: ${staleFlags.length} stale flags detected.
            Please remove or extend the following flags:
            ${staleFlags.map(f => `- ${f.key} (owner: ${f.owner}, age: ${f.ageInDays} days)`).join("\n")}
        `);
    }
}
 
// 2. Automated flag aging alerts
async function runFlagAgingCheck(): Promise<void> {
    const warningThreshold = days(60);
    const criticalThreshold = days(90);
    
    const agingFlags = await flagStore.getFlags({
        type: ["release", "experiment"],
        status: "active",
    });
    
    for (const flag of agingFlags) {
        const age = daysSince(flag.createdAt);
        
        if (age > criticalThreshold) {
            await alerting.sendCritical({
                to: flag.owner,
                cc: ["engineering-leads@company.com"],
                subject: `CRITICAL: Flag "${flag.key}" is ${age} days old`,
                message: `This flag has exceeded the maximum age policy. 
                          Immediate action required: remove the flag or request an exception.`,
            });
        } else if (age > warningThreshold) {
            await alerting.sendWarning({
                to: flag.owner,
                subject: `WARNING: Flag "${flag.key}" approaching age limit`,
                message: `This flag is ${age} days old. Plan for removal soon.`,
            });
        }
    }
}
 
// 3. Budget enforcement
async function createFlag(definition: FeatureFlagDefinition): Promise<void> {
    const currentCount = await flagStore.countFlags({
        service: definition.service,
        type: ["release", "experiment"],
        status: "active",
    });
    
    const budget = await getBudget(definition.service);
    
    if (currentCount >= budget.maxFlags) {
        throw new FlagBudgetExceededError(`
            Cannot create new flag: service "${definition.service}" 
            has ${currentCount}/${budget.maxFlags} active flags.
            Remove a stale flag first, or request a budget increase.
        `);
    }
    
    await flagStore.create(definition);
}

Enforcement Must Have Teeth

Policies that generate warnings but never block anything will be ignored. The most effective enforcement is blocking—deployment blocks for stale flags, creation blocks for budget violations. Teams adapt quickly when policies have real consequences.

Flag Removal Strategies

Removing flags is harder than creating them. The code has evolved around the flag, tests depend on it, and nobody remembers exactly what it controls. Here are battle-tested strategies for safe flag removal.

Strategy 1: The Two-Phase Removal

For critical flags, removal happens in two phases:

Phase 1: Hardcode the flag value

Change the flag evaluation to always return the target value
Deploy and monitor for issues
Leave the code structure intact

Phase 2: Remove the flag code

After confirming no issues (typically 1-2 weeks), remove the conditional
Delete the dead code path
Remove the flag definition

two-phase-removal.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
// Two-phase flag removal example
 
// ORIGINAL: Flag is active
async function processCheckout(order: Order): Promise<Result> {
    if (featureFlags.isEnabled("checkout-v2", { userId: order.userId })) {
        return this.newCheckoutService.process(order);
    }
    return this.legacyCheckoutService.process(order);
}
 
// PHASE 1: Hardcode the value (keep structure)
// This allows quick rollback by reverting this one change
async function processCheckout(order: Order): Promise<Result> {
    // Flag "checkout-v2" removal phase 1
    // Hardcoded to true - remove legacy path in next release
    if (true) {  
        return this.newCheckoutService.process(order);
    }
    return this.legacyCheckoutService.process(order);
}
 
// PHASE 2: Remove the flag and dead code
async function processCheckout(order: Order): Promise<Result> {
    return this.newCheckoutService.process(order);
}
 
// Also delete:
// - legacyCheckoutService (if no other usages)
// - Tests for legacy checkout path
// - Flag definition in flag management system

Strategy 2: Automated Flag Detection and Removal

For mature flag systems, automation can identify and even remove stale flags.

automated-flag-cleanup.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
// Automated flag cleanup tooling
 
interface FlagUsageAnalysis {
    flagKey: string;
    codeReferences: CodeReference[];
    lastEvaluated: Date | null;
    evaluationCount30Days: number;
    alwaysReturns: boolean | null;  // If flag always returns same value
    returnedValue?: any;
}
 
// 1. Static analysis: Find flag references in code
async function findFlagReferences(flagKey: string): Promise<CodeReference[]> {
    const grepResults = await exec(`
        grep -r "isEnabled.*${flagKey}" --include="*.ts" --include="*.tsx"
    `);
    
    return parseGrepResults(grepResults);
}
 
// 2. Runtime analysis: Check if flag is still being evaluated
async function getFlagEvaluationStats(flagKey: string): Promise<EvaluationStats> {
    // Query analytics/telemetry system
    return await analytics.query({
        metric: "feature_flag_evaluation",
        filters: { flag_key: flagKey },
        timeRange: days(30),
        groupBy: ["returned_value"],
    });
}
 
// 3. Generate cleanup report
async function generateCleanupReport(): Promise<CleanupReport> {
    const allFlags = await flagStore.getAllFlags();
    const analysis: FlagUsageAnalysis[] = [];
    
    for (const flag of allFlags) {
        const refs = await findFlagReferences(flag.key);
        const stats = await getFlagEvaluationStats(flag.key);
        
        analysis.push({
            flagKey: flag.key,
            codeReferences: refs,
            lastEvaluated: stats.lastEvaluated,
            evaluationCount30Days: stats.totalEvaluations,
            alwaysReturns: stats.uniqueReturnedValues.length === 1,
            returnedValue: stats.uniqueReturnedValues[0],
        });
    }
    
    // Identify candidates for removal
    const readyForRemoval = analysis.filter(a => 
        a.alwaysReturns === true &&  // Always returns same value
        a.evaluationCount30Days > 100  // Significant traffic to confirm
    );
    
    const neverUsed = analysis.filter(a => 
        a.evaluationCount30Days === 0 &&
        a.codeReferences.length > 0  // Still in code but never evaluated
    );
    
    const noCodeReferences = analysis.filter(a => 
        a.codeReferences.length === 0  // Flag exists but no code uses it
    );
    
    return { readyForRemoval, neverUsed, noCodeReferences, allAnalysis: analysis };
}
 
// 4. Generate removal PRs (for the brave)
async function generateRemovalPR(flagKey: string): Promise<void> {
    const references = await findFlagReferences(flagKey);
    
    for (const ref of references) {
        // Use AST manipulation to remove flag conditionals
        await removeConditionalFromFile(ref.filePath, flagKey);
    }
    
    // Create PR with changes
    await github.createPR({
        title: `[Automated] Remove stale feature flag: ${flagKey}`,
        body: `
            This PR removes the feature flag "${flagKey}" which has been 
            returning the same value for 30+ days.
            
            **Flag evaluation history:**
            - Last 30 days: always returned ${await getLastReturnedValue(flagKey)}
            - Evaluation count: ${await getEvaluationCount(flagKey)}
            
            **Removed from files:**
            ${references.map(r => `- ${r.filePath}:${r.lineNumber}`).join("\n")}
            
            Please review carefully and ensure no regressions.
        `,
    });
}

Cleanup as a Regular Practice

The most successful teams dedicate regular time to flag cleanup. Some run 'Flag Cleanup Fridays' where engineers spend an hour removing stale flags. Others include flag cleanup in sprint ceremonies. The key is making cleanup routine, not exceptional.

Flag Documentation and Discovery

When engineers can't discover what flags exist or understand what they do, flags become mysterious and untouchable. Documentation and discovery are essential for maintainability.

The Flag Catalog

Every flag should be discoverable through a searchable catalog with rich metadata:

flag-catalog-ui.tsx
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
// Example flag catalog data model
 
interface FlagCatalogEntry {
    // Identity
    key: string;
    name: string;
    description: string;
    
    // Classification
    type: FlagType;
    status: FlagStatus;
    
    // Ownership
    owner: TeamOrIndividual;
    createdBy: string;
    createdAt: Date;
    
    // Lifecycle
    expectedRemovalDate: Date | null;
    completedAt: Date | null;
    stale: boolean;  // Computed: past expected removal date
    
    // Links
    jiraTicket: string | null;
    designDoc: string | null;
    slackChannel: string | null;
    
    // Analytics
    lastEvaluated: Date | null;
    evaluationsLast7Days: number;
    returnsBreakdown: { value: any; percentage: number }[];
    
    // Code references (from static analysis)
    codeReferences: {
        repository: string;
        filePath: string;
        lineNumber: number;
    }[];
    
    // Targeting summary
    targetingSummary: string;  // "25% of users; 100% of internal users"
}
 
// Flag catalog UI showing critical information at a glance
function FlagCatalog({ flags }: { flags: FlagCatalogEntry[] }) {
    return (
        <div>
            <h1>Feature Flag Catalog</h1>
            
            {/* Filters */}
            <FilterBar>
                <TypeFilter options={["release", "experiment", "ops", "permission"]} />
                <StatusFilter options={["active", "complete", "stale"]} />
                <OwnerFilter />
                <TagFilter />
            </FilterBar>
            
            {/* Alerts for governance violations */}
            <StalePhlagsAlert flags={flags.filter(f => f.stale)} />
            
            {/* Main catalog */}
            <Table>
                <TableHeader>
                    <Column>Flag</Column>
                    <Column>Type</Column>
                    <Column>Status</Column>
                    <Column>Owner</Column>
                    <Column>Age</Column>
                    <Column>Last Evaluated</Column>
                    <Column>Actions</Column>
                </TableHeader>
                {flags.map(flag => (
                    <FlagRow key={flag.key} flag={flag} />
                ))}
            </Table>
        </div>
    );
}

Flag Catalog Features

•Search — Find flags by key, name, description, owner, or tags
•Filter — Filter by type, status, age, team, or repository
•Analytics — See evaluation counts, return value distribution, trends
•Code links — Click to jump to code references in each repository
•Governance dashboard — See stale flags, approaching deadlines, budget usage
•Audit log — Who changed what, when, with diffs of targeting rules
•Dependency graph — Visualize which flags interact with which others

Organizational Patterns for Flag Management

Technical solutions alone don't solve flag management. The organizational structure around flags is equally important.

Pattern 1: Flag Stewardship

Assign a person or rotating role responsible for flag health:

Weekly flag review — Review stale flags, nudge owners, escalate blockers
Monthly metrics report — Flag count, age distribution, cleanup velocity
Onboarding — Ensure new engineers understand flag governance
Policy evolution — Propose policy changes based on observed patterns

This doesn't need to be a full-time role. Rotating stewardship among senior engineers spreads knowledge and accountability.

Pattern 2: Flag Cleanup Rituals

Make cleanup a scheduled activity:

Flag Cleanup Friday — Weekly 1-hour session dedicated to flag removal
End-of-sprint cleanup — Include flag cleanup in sprint ceremonies
Release cleanup — Each major release includes flag cleanup as a checklist item
Quarterly amnesty — Dedicated time to clear the backlog of stale flags

Pattern 3: Team-Level Flag Budgets

Allocate a fixed "budget" of active release/experiment flags per team:

Team Size	Release Flag Budget	Experiment Flag Budget
Small (2-4)	5	3
Medium (5-8)	10	5
Large (9+)	15	8

When a team hits their budget, they must remove a flag before creating a new one. This creates natural pressure to clean up.

Pattern 4: Flag Graduation Workflow

Formalize the transition from "flag active" to "flag complete" to "flag removed":

flag-graduation-workflow.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
// Formalized flag graduation workflow
 
interface FlagGraduationWorkflow {
    steps: GraduationStep[];
}
 
const graduationWorkflow: FlagGraduationWorkflow = {
    steps: [
        {
            name: "Request Graduation",
            description: "Owner marks flag as ready for graduation",
            actions: [
                "Set status to 'graduation-requested'",
                "Notify flag steward",
            ],
            requiredApprovals: ["owner"],
        },
        {
            name: "Verify Complete Rollout",
            description: "Confirm flag is at 100% or target state",
            actions: [
                "Check targeting rules show 100% exposure",
                "Confirm no recent targeting changes",
            ],
            requiredApprovals: ["automated-check"],
        },
        {
            name: "Bake Period",
            description: "Wait for bake period with no issues",
            duration: days(7),
            actions: [
                "Monitor error rates",
                "Monitor performance metrics",
                "Check for user complaints",
            ],
            exitCondition: "No incidents related to this flag",
        },
        {
            name: "Code Removal PR",
            description: "Create PR to remove flag from code",
            actions: [
                "Generate flag removal PR (automated or manual)",
                "Include dead code removal",
                "Update/remove related tests",
            ],
            requiredApprovals: ["code-review", "qe-sign-off"],
        },
        {
            name: "Flag Deletion",
            description: "Remove flag from flag management system",
            actions: [
                "Archive flag metadata for historical reference",
                "Delete flag definition",
                "Update documentation if needed",
            ],
            requiredApprovals: ["flag-steward"],
        },
    ],
};

Make Cleanup the Default Path

The goal is to make flag removal the path of least resistance. If cleanup requires more effort than letting flags rot, rot will win. Automation, clear workflows, and management support for cleanup time all contribute to making removal easy.

Metrics and Health Monitoring

What gets measured gets managed. Tracking flag health metrics provides visibility and accountability.

Essential Flag Health Metrics
Metric	Description	Target	Action If Violated
Active Release Flags	Count of release flags in 'active' status	< 30 per service	Pause new flags; prioritize cleanup
Average Flag Age	Mean days since creation for active flags	< 30 days	Investigate oldest flags
Stale Flag Count	Flags past expected removal date	0	Escalate to owners immediately
Cleanup Velocity	Flags removed per sprint	≥ flags created	Dedicate cleanup time
Flag-to-Engineer Ratio	Active flags per engineer	< 3	Review flag necessity
100% Rolled Out Flags	Flags at 100% but not marked complete	0	Mark complete or explain
Orphaned Flags	Flags with no code references	0	Delete immediately

Flag Health Dashboard

Visualize these metrics in a dashboard visible to engineering leadership:

Trend lines showing flag count over time (should be stable, not growing)
Age distribution histogram showing how many flags are in each age bucket
Team comparison showing which teams have the most stale flags
Cleanup leaderboard celebrating teams that remove the most flags
Alerts for governance violations

Celebrate Cleanup

Teams that remove flags deserve recognition. Some organizations include 'flags cleaned up' in team metrics, celebrate flag cleanup in engineering all-hands, or run competitions for 'cleanest flag hygiene'. Positive reinforcement works.

Summary: Sustainable Flag Lifecycle Management

We've covered the complete landscape of flag lifecycle management. Let's consolidate:

Key Takeaways

•Four lifecycle phases — Creation, rollout, completion, cleanup. Each needs explicit processes.
•Governance requires enforcement — Policies without blocking mechanisms are ignored.
•Two-phase removal — Hardcode value first, remove code second for safety.
•Automation enables scale — Static analysis, runtime analytics, and automated PR generation make cleanup tractable.
•Documentation enables discovery — Flag catalogs with search, analytics, and code links are essential.
•Organizational patterns matter — Stewardship, rituals, budgets, and workflows institutionalize good behavior.
•Metrics drive improvement — Track flag health and make it visible to leadership.

What's next:

With lifecycle management in place, the final piece is testing. The next page covers how to test feature-flagged code effectively—including strategies for testing both flag variants, mocking flag state, and ensuring flag removal doesn't break production.

Page Complete

You now understand how to manage feature flags through their entire lifecycle. These practices prevent flag sprawl, ensure accountability, and make cleanup sustainable. Without lifecycle management, flags become permanent fixtures; with it, they remain the powerful temporary tools they were designed to be.