Feature Flag

Feature Flag and Progressive Delivery Rules

1. Toggle Classification

Based on Martin Fowler's Feature Toggles taxonomy, classify every flag before creation.

Classification Rules

• Every flag MUST have a category assigned at creation time
• Release toggles MUST have a planned removal date (default: 30 days after full rollout)
• Experiment toggles MUST define success metrics and evaluation criteria before activation
• Ops toggles MUST document the operational scenario they address
• Permission toggles MUST map to a defined entitlement or role

2. Flag Naming and Structure

Naming Convention

<category>.<domain>.<feature-name>

Full example: release.checkout.new-payment-flow

Flag Definition Schema

{
  "key": "release.checkout.new-payment-flow",
  "category": "release",
  "description": "Enables the redesigned payment flow with multi-step checkout",
  "owner": "team-payments",
  "created": "2026-03-01",
  "expiry": "2026-04-15",
  "default_value": false,
  "tags": ["checkout", "payments", "q1-release"]
}

Rules

• Flag keys MUST be globally unique
• Descriptions MUST explain what the flag controls, not just name it
• Every flag MUST have an owner (team or individual)
• Release and experiment flags MUST have an expiry date
• Use boolean flags for on/off; use string/JSON variants only when multiple states are needed

3. Flag Lifecycle Management

Lifecycle Phases

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ Created  │───▶│  Testing  │───▶│ Rollout  │───▶│  Stable  │───▶│ Removed  │
└──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘
     │                                │                              │
     │         Flag off in prod       │    Gradual % increase        │  Code cleanup
     │         On in dev/staging      │    Monitor metrics           │  Remove flag checks
     │                                │    Rollback if needed        │  Delete flag config

Phase Rules

Cleanup Enforcement

• Track flag age in CI — warn at 80% of expiry, fail build at 120% of expiry
• Run static analysis to detect stale flag references
• Maintain a flag inventory dashboard showing age, status, and owner
• Include flag cleanup in sprint planning when flags approach expiry

4. Targeting Rules and Percentage Rollouts

Targeting Hierarchy

Evaluate targeting rules in this order:

1. User-level override — specific user IDs (for testing or VIP access)
2. Segment match — user belongs to a defined segment (beta-testers, internal-staff)
3. Rule-based evaluation — attribute conditions (country == "US", plan == "enterprise")
4. Percentage rollout — consistent hashing of user ID for gradual rollout
5. Default value — fallback when no rules match

Percentage Rollout Rules

Recommended rollout schedule:

Day 1:   1%  — smoke test, verify metrics
Day 2:   5%  — expand, monitor error rates
Day 3:  10%  — check performance impact
Day 5:  25%  — broader exposure
Day 7:  50%  — half of traffic
Day 10: 100% — full rollout, begin cleanup timer

• Use consistent hashing (e.g., murmur3 of user ID + flag key) so users get a stable experience
• Never use random assignment for percentage rollouts — it causes flickering
• Define rollback criteria before starting rollout (error rate threshold, latency p99, conversion drop)
• Automate rollback when metrics breach defined thresholds

Targeting Rule Example

{
  "flag": "experiment.checkout.one-click-buy",
  "rules": [
    {
      "priority": 1,
      "condition": { "user_id": { "in": ["user-123", "user-456"] } },
      "value": true
    },
    {
      "priority": 2,
      "condition": { "segment": "beta-testers" },
      "value": true
    },
    {
      "priority": 3,
      "condition": { "country": "US", "plan": "premium" },
      "value": true,
      "percentage": 50
    }
  ],
  "default": false
}

5. Trunk-Based Development with Feature Flags

Core Pattern

Feature flags enable trunk-based development by decoupling deployment from release.

┌─────────────────────────────────────────────────────────┐
│                     main branch                         │
│  ──●──●──●──●──●──●──●──●──●──●──●──●──●──●──●──●──▶  │
│    │     │        │           │        │                 │
│   Add   Impl    Impl       Wire     Remove              │
│   flag  behind  more       100%     flag                │
│         flag    logic      rollout  + code              │
└─────────────────────────────────────────────────────────┘

Trunk-Based Development Rules

• Merge to main frequently (at least daily) — feature flags protect incomplete work
• Never use long-lived feature branches when a release flag can achieve the same goal
• Wrap all incomplete or risky code paths behind release flags
• Deploy flag-guarded code to production even if the feature is not ready for users
• Use flag-driven deployment (deploy code) vs flag-driven release (enable feature) as separate steps

Anti-Patterns to Avoid

6. OpenFeature Standard

OpenFeature is the CNCF open standard for feature flag evaluation.

Architecture

┌─────────────┐     ┌──────────────────┐     ┌──────────────────┐
│ Application │────▶│  OpenFeature SDK │────▶│    Provider       │
│   Code      │     │  (Vendor-neutral)│     │ (LaunchDarkly,   │
│             │     │                  │     │  Unleash, Flipt,  │
│             │     │  ┌────────────┐  │     │  Flagsmith, etc.) │
│             │     │  │   Hooks    │  │     └──────────────────┘
│             │     │  └────────────┘  │
└─────────────┘     └──────────────────┘

Key Rules

• Use OpenFeature SDK as the abstraction layer — never call provider APIs directly
• Register a single provider per application instance
• Use evaluation context to pass user attributes for targeting
• Implement hooks for logging, metrics, and validation — not in application code
• For detailed API usage and provider implementation, see references/openfeature-standard.md

Basic Usage Pattern

import { OpenFeature } from '@openfeature/server-sdk';

// Set provider once at startup
OpenFeature.setProvider(new YourProvider());

const client = OpenFeature.getClient();

// Evaluate with context
const showFeature = await client.getBooleanValue(
  'release.checkout.new-payment-flow',
  false, // default value
  { targetingKey: userId, country: userCountry }
);

7. Testing Strategy

Test Both Paths

Every flag evaluation point MUST have tests for both the flag-on and flag-off states.

Test Matrix for a Single Flag:

┌───────────────┬──────────┬──────────┐
│   Scenario    │ Flag ON  │ Flag OFF │
├───────────────┼──────────┼──────────┤
│ Unit test     │    ✓     │    ✓     │
│ Integration   │    ✓     │    ✓     │
│ E2E (staging) │    ✓     │    ✓     │
│ E2E (prod)    │  Canary  │ Default  │
└───────────────┴──────────┴──────────┘

Testing Rules

• Use test-specific providers (in-memory) that let you set flag values per test
• Never depend on external flag service in unit tests
• Integration tests MAY connect to a test-environment flag service
• Test the default/fallback path — assume the flag service will be unavailable
• For experiment flags, test that metrics are emitted correctly in both variants

Test Helper Pattern

// Test helper: override flags for testing
function withFlags(overrides: Record<string, boolean>, fn: () => void) {
  const testProvider = new InMemoryProvider(overrides);
  OpenFeature.setProvider(testProvider);
  try {
    fn();
  } finally {
    OpenFeature.clearProvider();
  }
}

// Usage in test
withFlags({ 'release.checkout.new-payment-flow': true }, () => {
  const result = renderCheckoutPage();
  expect(result).toContain('multi-step');
});

8. Security Considerations

Server-Side vs Client-Side Evaluation

Security Rules

• NEVER expose permission flag rules or targeting logic to client-side code
• Use server-side evaluation for any flag that controls access to paid features or sensitive data
• Client-side SDKs should receive only the evaluated result, not the full rule set
• Rotate API keys for flag services on the same schedule as other service credentials
• Audit flag changes — every flag modification must be logged with who, what, when
• Restrict flag modification permissions by environment (dev: team-wide, prod: restricted)

Audit Requirements

9. Progressive Delivery Integration

Feature flags integrate with progressive delivery to minimize blast radius.

Strategy Overview

Integration Rules

• Combine infrastructure-level delivery (canary, blue-green) with feature flags for maximum control
• Use feature flags for user-level targeting and infrastructure tools for instance-level routing
• Define automated rollback triggers for both layers
• Monitor both infrastructure metrics (CPU, memory, error rate) and business metrics (conversion, revenue)
• For detailed progressive delivery strategies, see references/progressive-delivery.md

10. Flag Technical Debt Management

Debt Indicators

Cleanup Process

1. Identify — Static analysis scan for flag references in code
2. Verify — Confirm flag is at 100% or 0% and stable for > 7 days
3. Remove code — Delete flag checks and the unused code path
4. Remove config — Delete flag definition from the flag service
5. Verify deployment — Deploy cleanup and confirm no regressions

CI Integration

# Example: Flag hygiene check in CI
flag-hygiene:
  script:
    - python scripts/check_flag_expiry.py --warn-days 7 --fail-days -14
    - python scripts/find_orphaned_flags.py --source-dir src/ --flag-config flags.json
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

11. Platform Comparison

Selection Guidance

• Need SaaS with advanced targeting → LaunchDarkly
• Need self-hosted with privacy → Unleash
• Need GitOps-native with declarative config → Flipt
• Need open-source with A/B testing → Flagsmith
• Need vendor-neutral code → Use OpenFeature SDK regardless of provider choice