promote-feature

# promote-feature Guides the staged promotion of a gated `FeatureFlag` variant to Dogfood, Preview, or Stable, and schedules the follow-up cleanup. ## Overview Feature flags have two interacting layers: - **Runtime** (`warp_core/src/features.rs`): `DOGFOOD_FLAGS`, `PREVIEW_FLAGS`, `RELEASE_FLAGS` — enabled per-channel at startup. - **Compile-time** (`app/Cargo.toml` + `app/src/lib.rs`): Cargo features in `[features]`. The `default = [...]` array enables a feature for all builds. `enabled_features()` in `app/src/lib.rs` bridges each Cargo feature to its `FeatureFlag` variant via `#[cfg(feature = "...")]`. **Do not remove the flag immediately after promoting to Stable.** Keep it for at least 1–2 release cycles so a rollback is a one-line PR (remove the entry from `default`). Use the `remove-feature-flag` skill for the cleanup step later. ## TUI note The per-channel arrays in `warp_core/src/features.rs` (`DOGFOOD_FLAGS`/`PREVIEW_FLAGS`/`RELEASE_FLAGS`) are shared and drive both the GUI desktop app (`app/`) and the headless TUI (`crates/warp_tui`) at runtime. The `app/Cargo.toml` `default` + `app/src/lib.rs` `enabled_features()` compile-time bridge is GUI-app-only. If a promoted feature should also reach the TUI, make sure it is enabled at runtime for the target channel (the shared arrays already do this) and, if the feature relies on a compile-time Cargo feature, that the TUI binary (`crates/warp_tui/Cargo.toml`) enables it too. ## Promote to Dogfood Add the flag to `DOGFOOD_FLAGS` in `warp_core/src/features.rs`: ```rust pub const DOGFOOD_FLAGS: &[FeatureFlag] = &[ // ... FeatureFlag::YourFeature, ]; ``` No other file changes needed. ## Promote to Preview 1. Add to `PREVIEW_FLAGS` in `warp_core/src/features.rs`. 2. Remove from `DOGFOOD_FLAGS` if present — Preview flags are automatically included in Dogfood builds. ```rust pub const PREVIEW_FLAGS: &[FeatureFlag] = &[ // ... FeatureFlag::YourFeature, ]; ``` ## Promote to Stable This requires changes in **three files**. ### 1. `app/Cargo.toml` — add to `default` Add the snake_case feature name to the `default = [...]` array: ```toml default = [ # ... "your_feature_name", ] ``` Prefer this over adding to `RELEASE_FLAGS` (see comment at `warp_core/src/features.rs:787-790`). It compiles the feature into all builds and enables a one-line rollback. ### 2. `app/src/lib.rs` — add to `enabled_features()` bridge Add a `#[cfg(...)]` entry inside the `flags.extend([...])` block in `enabled_features()`, following the existing pattern: ```rust #[cfg(feature = "your_feature_name")] FeatureFlag::YourFeature, ``` Place it near logically related entries. ### 3. `warp_core/src/features.rs` — remove from `PREVIEW_FLAGS` / `DOGFOOD_FLAGS` Remove the variant from whichever arrays it currently lives in: ```rust pub const PREVIEW_FLAGS: &[FeatureFlag] = &[ // Remove FeatureFlag::YourFeature, ]; ``` ### Validate ```bash cargo clippy -p warp_core --all-targets --tests -- -D warnings # Also lint the GUI app when app/Cargo.toml or app/src/lib.rs changed. cargo clippy -p warp --all-targets --tests -- -D warnings # Also lint the TUI when crates/warp_tui/Cargo.toml changed. cargo clippy -p warp_tui --all-targets --tests -- -D warnings ./script/format ``` If the promotion changes behavior beyond flag lists or configuration, run affected tests before Clippy. Format once after all other changes are complete. Do not rerun earlier checks after formatting or add a full presubmit unless explicitly required; CI owns broader platform and workspace coverage. ### Create a follow-up Linear issue After the PR lands, create a Linear issue to remind the team to remove the flag. Use the Linear MCP tool: ``` save_issue( title: "Remove FeatureFlag::YourFeature after stabilization", team: <your team>, assignee: "me", description: "FeatureFlag::YourFeature was promoted to Stable in <PR link>. Remove the flag and dead code branches after 1–2 release cycles. Follow the `remove-feature-flag` skill.", labels: ["tech-debt"], priority: 4 // Low ) ```