102 lines
3.2 KiB
Markdown
102 lines
3.2 KiB
Markdown
---
|
||
name: promote-feature
|
||
description: Promote a feature-flagged feature to Dogfood, Preview, or Stable in the Warp codebase. Use when a feature behind a FeatureFlag is ready to roll out to a broader audience, including wiring up the compile-time/runtime bridge and deferring flag cleanup safely.
|
||
---
|
||
|
||
# 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.
|
||
|
||
## 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
|
||
./script/format
|
||
cargo clippy --workspace --all-targets --all-features --tests -- -D warnings
|
||
```
|
||
|
||
### 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
|
||
)
|
||
```
|