Files
skills/public/flag_retirement_workflow.md

11 KiB

Feature Flag Retirement Workflow

Production-ready workflow for safely retiring feature flags with checklists, timelines, and automation.

Overview

Feature flag retirement is critical to prevent technical debt. This workflow ensures safe, systematic flag removal.

Retirement Phases

Phase 1: Identification (Week 1)

Objective: Identify flags ready for retirement

Checklist:

  • Flag has been at 100% rollout for 30+ days
  • No active experiments using this flag
  • No customer-facing issues reported
  • Flag variation is consistently used (>99%)
  • Business stakeholders approve removal
  • Technical team reviews impact

Analysis:

# Check flag usage
./analyze_flag_usage.py track --flag feature-x --days 90

# Check stale flags
./analyze_flag_usage.py stale --threshold 90 --flags-file flags.json

# Get retirement recommendations
./analyze_flag_usage.py recommend-retire \
    --confidence 0.8 \
    --flags-file flags.json

Criteria for Retirement:

  1. Age: Flag is 90+ days old
  2. Stability: No changes in 30+ days
  3. Consistency: Single variation used >99% of time
  4. Impact: Low risk to business operations
  5. Dependencies: No other flags depend on it

Output: List of candidate flags with confidence scores

Phase 2: Planning (Week 2)

Objective: Create detailed retirement plan

Tasks:

  1. Code Analysis

    # Find all code references
    grep -r "feature-x" --include="*.py" --include="*.js" .
    
    # Or use the analysis tool
    ./analyze_flag_usage.py debt --flag feature-x --flags-file flags.json
    
  2. Dependency Mapping

    • Identify services using the flag
    • Check for SDK integrations
    • Review analytics/monitoring dependencies
    • Document configuration files
  3. Impact Assessment

    Area Impact Level Notes
    Frontend Low Only in 2 components
    Backend Medium Used in 5 services
    Mobile None Not used
    Analytics High Multiple dashboards
    Tests Medium 15 tests reference flag
  4. Rollback Plan

    • Document how to re-enable if needed
    • Identify monitoring metrics
    • Define rollback triggers

Output: Retirement plan document

Phase 3: Communication (Week 2-3)

Objective: Notify stakeholders and prepare teams

Communication Plan:

  1. Announcement (Week 2, Monday)

    Subject: Feature Flag Retirement: feature-x
    
    We plan to retire the 'feature-x' feature flag in 2 weeks.
    
    Timeline:
    - Week 3: Code cleanup begins
    - Week 4: Flag removed from codebase
    - Week 5: Monitoring period
    
    Impact:
    - [List affected areas]
    
    Action Required:
    - Review your services for dependencies
    - Update documentation
    - Notify your team
    
    Questions? Contact: [Team]
    
  2. Team Notifications

    • Engineering teams
    • Product managers
    • QA/Testing teams
    • DevOps/SRE
    • Support team
  3. Documentation Updates

    • Update feature flag registry
    • Mark flag as "deprecated" in code
    • Add warnings to SDK calls

Checklist:

  • Sent announcement email
  • Posted in Slack/Teams channels
  • Updated Jira/Linear tickets
  • Marked flag as deprecated in LaunchDarkly/Unleash
  • Updated README and docs

Phase 4: Deprecation (Week 3)

Objective: Mark flag as deprecated and prepare for removal

Steps:

  1. Add Deprecation Warnings

    # Python example
    import warnings
    
    def check_feature_x():
        warnings.warn(
            "feature-x flag is deprecated and will be removed in v2.0",
            DeprecationWarning,
            stacklevel=2
        )
        return feature_flags.is_enabled('feature-x')
    
    // JavaScript example
    function checkFeatureX() {
        console.warn('feature-x flag is deprecated and will be removed in v2.0');
        return featureFlags.isEnabled('feature-x');
    }
    
  2. Update Flag Metadata

    # Using management tool
    ./manage_feature_flags.py update \
        --key feature-x \
        --environment production \
        --description "DEPRECATED: Will be removed 2025-02-01"
    
  3. Add Tests for Removal

    # Test that flag can be safely removed
    def test_feature_x_removal():
        # Verify default behavior
        result = get_feature_behavior(flag_enabled=False)
        assert result == expected_default_behavior
    
        # Verify flag enabled behavior (should be same)
        result = get_feature_behavior(flag_enabled=True)
        assert result == expected_default_behavior
    

Checklist:

  • Deprecation warnings added
  • Flag marked as deprecated in provider
  • Tests verify removal safety
  • Monitoring alerts updated
  • Documentation reflects deprecation

Phase 5: Code Cleanup (Week 4)

Objective: Remove flag references from code

Process:

  1. Create Feature Branch

    git checkout -b remove-feature-x-flag
    
  2. Remove Flag Checks

    # Before
    if feature_flags.is_enabled('feature-x'):
        new_implementation()
    else:
        legacy_implementation()
    
    # After (keep winning variation)
    new_implementation()
    
  3. Remove Unused Code

    • Delete legacy code paths
    • Remove conditional logic
    • Clean up imports
    • Update comments
  4. Update Tests

    # Before
    @parametrize('flag_enabled', [True, False])
    def test_feature_x(flag_enabled):
        # Test both paths
        pass
    
    # After
    def test_feature_x():
        # Test single path
        pass
    
  5. Update Documentation

    • Remove flag from feature flag registry
    • Update architecture docs
    • Clean up onboarding guides

Automated Cleanup Tool:

# Find and replace
find . -type f -name "*.py" -exec sed -i '' \
    '/feature-x/d' {} +

# Verify changes
git diff --stat

Checklist:

  • All flag checks removed
  • Legacy code paths deleted
  • Tests updated
  • Documentation updated
  • Code reviewed
  • All tests passing

Phase 6: Flag Removal (Week 4-5)

Objective: Remove flag from provider and configuration

Steps:

  1. Disable Flag

    ./manage_feature_flags.py toggle \
        --key feature-x \
        --environment production \
        --enabled false
    
  2. Monitor for 48 Hours

    • Check error rates
    • Review user complaints
    • Monitor performance metrics
    • Verify rollback readiness
  3. Archive Flag (After monitoring period)

    ./manage_feature_flags.py archive \
        --key feature-x \
        --environment production
    
  4. Remove from Code (After archive)

    git add .
    git commit -m "Remove feature-x flag after successful rollout"
    git push origin remove-feature-x-flag
    
  5. Deploy Changes

    • Deploy to staging
    • Run integration tests
    • Deploy to production
    • Monitor rollout

Monitoring Checklist:

  • Error rates stable
  • Performance metrics unchanged
  • No customer complaints
  • Rollback plan tested
  • On-call team notified

Phase 7: Verification (Week 5-6)

Objective: Verify complete removal and cleanup

Verification Steps:

  1. Code Search

    # Ensure no references remain
    grep -r "feature-x" . --include="*.py" --include="*.js"
    
    # Should return no results
    
  2. Provider Verification

    # Verify flag is archived
    ./manage_feature_flags.py list \
        --environment production \
        --archived true | grep feature-x
    
  3. Monitoring Review

    • 7 days of metrics post-removal
    • No anomalies detected
    • Performance stable
  4. Documentation Audit

    • Flag removed from all docs
    • Blog posts updated
    • Training materials current

Final Checklist:

  • No code references found
  • Flag archived in provider
  • 7 days of stable metrics
  • Documentation updated
  • Team notified of completion
  • Postmortem written (if issues)

Timeline Summary

Week Phase Key Activities
1 Identification Analyze usage, get approvals
2 Planning Map dependencies, create plan
2-3 Communication Notify stakeholders
3 Deprecation Mark deprecated, add warnings
4 Code Cleanup Remove flag checks
4-5 Flag Removal Archive flag, deploy changes
5-6 Verification Confirm complete removal

Automation Scripts

1. Flag Retirement Candidate Finder

#!/bin/bash
# find_retirement_candidates.sh

./analyze_flag_usage.py recommend-retire \
    --confidence 0.8 \
    --flags-file flags.json \
    --json > candidates.json

# Generate report
./analyze_flag_usage.py report \
    --results candidates.json \
    --format html \
    --output retirement_candidates.html

2. Code Reference Scanner

#!/bin/bash
# scan_flag_references.sh

FLAG_KEY=$1

echo "Scanning for references to: $FLAG_KEY"

# Find in code
echo "=== Code References ==="
rg "$FLAG_KEY" --type py --type js --type go

# Find in configs
echo "=== Config References ==="
find . -name "*.yaml" -o -name "*.json" | xargs grep "$FLAG_KEY"

# Find in tests
echo "=== Test References ==="
rg "$FLAG_KEY" --glob "*test*"

3. Safe Removal Verifier

#!/bin/bash
# verify_safe_removal.sh

FLAG_KEY=$1

echo "Verifying safe removal of: $FLAG_KEY"

# Check usage stats
./analyze_flag_usage.py track --flag "$FLAG_KEY" --days 90

# Check for dependencies
./analyze_flag_usage.py debt --flag "$FLAG_KEY"

# Run tests
pytest tests/ -v

echo "Verification complete"

Rollback Procedures

Emergency Rollback

If issues detected after flag removal:

  1. Immediate Response (0-15 minutes)

    # Revert deployment
    kubectl rollout undo deployment/app
    
    # Or revert via CD tool
    argocd app rollback app-production
    
  2. Re-enable Flag (15-30 minutes)

    # Re-create flag if deleted
    ./manage_feature_flags.py create \
        --key feature-x \
        --name "Feature X (Restored)" \
        --type release \
        --variations '{"on": true, "off": false}' \
        --default off \
        --enabled
    
  3. Communication (30-60 minutes)

    • Notify stakeholders
    • Update incident tracker
    • Schedule postmortem

Best Practices

  1. Never Rush: Take full 6 weeks if needed
  2. Monitor Continuously: Watch metrics at each phase
  3. Communicate Early: Notify teams early and often
  4. Document Everything: Keep detailed records
  5. Test Thoroughly: Verify each step
  6. Plan Rollback: Always have escape plan
  7. Learn from Issues: Write postmortems

Common Pitfalls

  • Removing too quickly: Skipping monitoring periods
  • Missing dependencies: Not checking all services
  • Poor communication: Surprising teams with changes
  • No rollback plan: Unable to revert if issues
  • Incomplete removal: Leaving dead code/configs

Success Metrics

  • Time to retirement: < 6 weeks
  • Zero production incidents
  • No customer impact
  • Complete code removal
  • Team satisfaction: High

Tools Reference

  • manage_feature_flags.py: Flag CRUD operations
  • analyze_flag_usage.py: Usage analytics
  • test_flag_variations.py: Validation testing

Conclusion

Follow this workflow to safely retire feature flags without disruption. Take time, communicate well, and monitor carefully.