103 lines
2.9 KiB
Markdown
103 lines
2.9 KiB
Markdown
---
|
|
name: add-feature-flag
|
|
description: Add a new feature flag to gate code changes in the Warp codebase.
|
|
---
|
|
|
|
# add-feature-flag
|
|
|
|
Add a new feature flag to gate code changes in the Warp codebase.
|
|
|
|
## Overview
|
|
|
|
Feature flags in Warp are compile-time flags that allow features to be selectively enabled for different channels (e.g.: Dev, Stable). They use a small runtime plumbing layer that checks if a flag is enabled.
|
|
|
|
## Steps
|
|
|
|
### 1. Add to Cargo.toml
|
|
Add the feature to `app/Cargo.toml` under the `[features]` section, but **NOT** under the `default` nested stanza:
|
|
|
|
```toml
|
|
[features]
|
|
your_feature_name = []
|
|
```
|
|
|
|
### 2. Add to FeatureFlag enum
|
|
Add a new variant to the `FeatureFlag` enum in `warp_core/src/features.rs`:
|
|
|
|
```rust
|
|
#[derive(Sequence)]
|
|
pub enum FeatureFlag {
|
|
YourFeatureName,
|
|
}
|
|
```
|
|
|
|
### 3. Add conditional compilation directive
|
|
Add the feature to `app/src/lib.rs` with a corresponding `#[cfg(feature = "...")]` attribute to ensure it's only included when enabled:
|
|
|
|
```rust
|
|
#[cfg(feature = "your_feature_name")]
|
|
YourFeatureName,
|
|
```
|
|
|
|
### 4. Gate code with runtime checks
|
|
In your code, use the runtime check to conditionally execute feature-gated code:
|
|
|
|
```rust
|
|
if FeatureFlag::YourFeatureName.is_enabled() {
|
|
// feature-gated behavior
|
|
}
|
|
```
|
|
|
|
### 5. (Optional) Enable for dogfood builds
|
|
To enable the feature by default for Dev/dogfood builds, add it to the `DOGFOOD_FLAGS` array in `features.rs`:
|
|
|
|
```rust
|
|
pub const DOGFOOD_FLAGS: &[FeatureFlag] = &[
|
|
FeatureFlag::YourFeatureName,
|
|
];
|
|
```
|
|
|
|
### 6. Running with feature flags
|
|
To test locally with the feature enabled:
|
|
|
|
```bash
|
|
cargo run --features your_feature_name
|
|
|
|
# Multiple features:
|
|
cargo run --features your_feature_name,another_feature
|
|
```
|
|
|
|
## Keybindings with Feature Flags
|
|
|
|
If adding an `EditableBinding` or `FixedBinding` that's part of a gated feature, include an enabled predicate that checks the feature flag. This prevents the keybinding from appearing in keyboard settings when the feature is disabled.
|
|
|
|
Example:
|
|
```rust
|
|
EditableBinding::new(
|
|
"action:name",
|
|
"Action description",
|
|
YourAction::Variant
|
|
)
|
|
.with_enabled(|| FeatureFlag::YourFeatureName.is_enabled())
|
|
.with_key_binding("cmdorctrl-key")
|
|
```
|
|
|
|
## Rolling Out to Stable
|
|
|
|
When ready to enable the feature for all Warp Stable users, add it to the `default` array in `app/Cargo.toml`:
|
|
|
|
```toml
|
|
[features]
|
|
default = [
|
|
"your_feature_name",
|
|
# other default features...
|
|
]
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
- **Prefer runtime checks over cfg directives**: Use `FeatureFlag::YourFeatureName.is_enabled()` instead of `#[cfg(...)]` when possible, so flags can be toggled without recompilation and are easier to clean up later
|
|
- Use `#[cfg(...)]` only when code cannot compile without the flag (e.g., platform-specific code or missing dependencies)
|
|
- Keep flags high-level and product-focused rather than per-call-site
|
|
- Remove flags and dead branches after launch has stabilized
|