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:
- Age: Flag is 90+ days old
- Stability: No changes in 30+ days
- Consistency: Single variation used >99% of time
- Impact: Low risk to business operations
- 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:
-
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 -
Dependency Mapping
- Identify services using the flag
- Check for SDK integrations
- Review analytics/monitoring dependencies
- Document configuration files
-
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 -
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:
-
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] -
Team Notifications
- Engineering teams
- Product managers
- QA/Testing teams
- DevOps/SRE
- Support team
-
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:
-
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'); } -
Update Flag Metadata
# Using management tool ./manage_feature_flags.py update \ --key feature-x \ --environment production \ --description "DEPRECATED: Will be removed 2025-02-01" -
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:
-
Create Feature Branch
git checkout -b remove-feature-x-flag -
Remove Flag Checks
# Before if feature_flags.is_enabled('feature-x'): new_implementation() else: legacy_implementation() # After (keep winning variation) new_implementation() -
Remove Unused Code
- Delete legacy code paths
- Remove conditional logic
- Clean up imports
- Update comments
-
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 -
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:
-
Disable Flag
./manage_feature_flags.py toggle \ --key feature-x \ --environment production \ --enabled false -
Monitor for 48 Hours
- Check error rates
- Review user complaints
- Monitor performance metrics
- Verify rollback readiness
-
Archive Flag (After monitoring period)
./manage_feature_flags.py archive \ --key feature-x \ --environment production -
Remove from Code (After archive)
git add . git commit -m "Remove feature-x flag after successful rollout" git push origin remove-feature-x-flag -
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:
-
Code Search
# Ensure no references remain grep -r "feature-x" . --include="*.py" --include="*.js" # Should return no results -
Provider Verification
# Verify flag is archived ./manage_feature_flags.py list \ --environment production \ --archived true | grep feature-x -
Monitoring Review
- 7 days of metrics post-removal
- No anomalies detected
- Performance stable
-
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:
-
Immediate Response (0-15 minutes)
# Revert deployment kubectl rollout undo deployment/app # Or revert via CD tool argocd app rollback app-production -
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 -
Communication (30-60 minutes)
- Notify stakeholders
- Update incident tracker
- Schedule postmortem
Best Practices
- Never Rush: Take full 6 weeks if needed
- Monitor Continuously: Watch metrics at each phase
- Communicate Early: Notify teams early and often
- Document Everything: Keep detailed records
- Test Thoroughly: Verify each step
- Plan Rollback: Always have escape plan
- 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 operationsanalyze_flag_usage.py: Usage analyticstest_flag_variations.py: Validation testing
Conclusion
Follow this workflow to safely retire feature flags without disruption. Take time, communicate well, and monitor carefully.