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
)