<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/contributor-success/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Close this issue](https://contributors.gitlab.com/manage-issue?action=close&projectId=278964&issueIid=564825) </details> <!--IssueSummary end--> ## Summary Following the root cause analysis in #562149+, we need to update our feature flag documentation to prevent upgrade compatibility issues during zero-downtime upgrades. ## Background During zero-downtime upgrades from 17.11.6 to 18.0.4, pipeline job retries failed because the `ci_only_one_persistent_ref_creation` feature flag was removed without ever being enabled by default. This created inconsistent behavior between Rails and Sidekiq nodes during the upgrade window. ## Proposed Changes ### 1. Update Feature Flag Development Documentation Add guidance to https://docs.gitlab.com/development/feature_flags/ about: - Enforcing feature flags to be enabled by default for at least one milestone before removal - Cross-version compatibility considerations during zero-downtime upgrades - Reference this incident (#562149) as an example of what can go wrong ### 2. Enhance Code Review Acceptance Checklist Update https://docs.gitlab.com/development/code_review/#acceptance-checklist to include: - Explicit check for feature flag removal compatibility - Requirement to verify feature flags are enabled by default before removal, or clearly document why they haven't been enabled - Upgrade compatibility review when removing feature flags that gate cleanup or state management logic ## Acceptance Criteria - [ ] Feature flag documentation includes guidance on enabling flags by default before removal - [ ] Feature flag documentation references the upgrade compatibility incident - [ ] Code review checklist includes feature flag removal compatibility check - [ ] Documentation changes are reviewed by relevant teams ## Related Issues - Root cause analysis: #562149 - Original bug report: #558808