MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-04-28 22:14:52 -07:00
Code Issues Packages Projects Releases Wiki Activity

feat(core): implement feature lifecycle management (Alpha, Beta, GA)

Browse Source
This commit is contained in:
Jerop Kipruto
2026-02-16 23:48:45 -05:00
parent 6aa6630137
commit 04f22a51b1
23 changed files with 1678 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/cli/feature-lifecycle.md
+193
View File
@@ -0,0 +1,193 @@
# Feature Lifecycle
Gemini CLI uses a **Feature Lifecycle** management system to handle the
introduction, maturation, and deprecation of new and optional features.
- [Feature Lifecycle](#feature-lifecycle)
- [Feature Stages](#feature-stages)
- [Configuration](#configuration)
- [Precedence and Reconciliation](#precedence-and-reconciliation)
- [Available Features](#available-features)
- [Managing Feature Lifecycle](#managing-feature-lifecycle)
- [Adding a Feature](#adding-a-feature)
- [Promoting a Feature](#promoting-a-feature)
- [Deprecating a Feature](#deprecating-a-feature)
- [Removing a Feature](#removing-a-feature)
- [Relevant Documentation](#relevant-documentation)
## Feature Stages
Features progress through the following stages:
| Stage | Default | UI Badge | Description |
| -------------- | -------- | -------------- | ------------------------------------------------------------------------------------------- |
| **ALPHA** | Disabled | `[ALPHA]` | Early-access features. May be unstable, change significantly, or be removed without notice. |
| **BETA** | Enabled | `[BETA]` | Features that are well-tested and considered stable. Can be disabled if issues arise. |
| **GA** | Enabled | - | Stable features that are part of the core product. Cannot be disabled. |
| **DEPRECATED** | Disabled | `[DEPRECATED]` | Features scheduled for removal. Using them triggers a warning. |
## Configuration
The feature lifecycle can be configured in several ways:
1. **`settings.json`**: Use the `features` object to toggle specific features
or entire stages.
- `features.allAlpha`: Enable/disable all Alpha features.
- `features.allBeta`: Enable/disable all Beta features.
- `features.<featureName>`: Toggle an individual feature.
2. **CLI Flag**: Use `--feature-gates="feat1=true,feat2=false"` for runtime
overrides.
3. **Environment Variable**: Set
`GEMINI_FEATURE_GATES="feat1=true,feat2=false"`.
The stability of each feature is visually indicated in the
[`/settings` UI](/docs/cli/settings.md) with colored badges. **GA** features are
considerd stable and look identical to standard settings.
### Precedence and Reconciliation
When determining if a feature is enabled, the system follows this order of
precedence (highest priority first):
1. **Global Lock**: Features in the **GA** stage are locked to `true` and cannot
be disabled.
2. **CLI Flags & Environment Variables**: Runtime overrides (`--feature-gates`
or `GEMINI_FEATURE_GATES`) override persistent settings.
3. **Individual Toggle**: Specific feature toggles in `settings.json` (e.g.,
`"features": { "plan": true }`).
4. **Meta Toggles**: Stage-wide toggles in `settings.json` (`allAlpha` or
`allBeta`). For example, if `allAlpha` is `true`, all Alpha features are
enabled unless specifically disabled by an individual toggle.
5. **Stage Default**: The inherent default for the feature's current stage
(Alpha: Disabled, Beta/GA: Enabled).
For more details on persistent configuration, see the [Configuration guide].
## Available Features
<!-- FEATURES-AUTOGEN:START -->
| Feature | Stage | Default | Since | Description |
| --------------------- | ----- | -------- | ------ | ----------------------------------------------------------- |
| `enableAgents` | ALPHA | Disabled | 0.30.0 | Enable local and remote subagents. |
| `extensionConfig` | BETA | Enabled | 0.30.0 | Enable requesting and fetching of extension settings. |
| `extensionManagement` | BETA | Enabled | 0.30.0 | Enable extension management features. |
| `extensionRegistry` | ALPHA | Disabled | 0.30.0 | Enable extension registry explore UI. |
| `extensionReloading` | ALPHA | Disabled | 0.30.0 | Enables extension loading/unloading within the CLI session. |
| `jitContext` | ALPHA | Disabled | 0.30.0 | Enable Just-In-Time (JIT) context loading. |
| `plan` | ALPHA | Disabled | 0.30.0 | Enable planning features (Plan Mode and tools). |
| `toolOutputMasking` | BETA | Enabled | 0.30.0 | Enables tool output masking to save tokens. |
| `useOSC52Paste` | ALPHA | Disabled | 0.30.0 | Use OSC 52 sequence for pasting. |
| `zedIntegration` | ALPHA | Disabled | 0.30.0 | Enable Zed integration. |
<!-- FEATURES-AUTOGEN:END -->
## Managing Feature Lifecycle
Maintaining a feature involves promoting it through stages or eventually
deprecating and removing it.
### Adding a Feature
To add a new feature under lifecycle management:
1. **Define the Feature**: Add a new entry to [`FeatureDefinitions`] in
[`features.ts`].
```typescript
export const FeatureDefinitions: Record<string, FeatureSpec[]> = {
// ... existing features
myNewFeature: [
{
lockToDefault: false,
preRelease: FeatureStage.Alpha,
since: '0.31.0',
description: 'Description of my new feature.',
},
],
};
```
_Note: The `default` field is optional. If omitted, it defaults to `false`
for Alpha/Deprecated and `true` for Beta/GA._
2. **Expose in Settings**: Add the feature to the `features` object in
[`settingsSchema.ts`]. This ensures it appears in the `/settings` UI and is
validated.
```typescript
features: {
// ...
properties: {
// ...
myNewFeature: {
type: 'boolean',
label: 'My New Feature',
category: 'Features',
requiresRestart: true, // or false
description: 'Description of my new feature.',
showInDialog: true,
},
},
},
```
3. **Use the Feature**: In your code, check if the feature is enabled using the
`Config` object.
```typescript
if (this.config.isFeatureEnabled('myNewFeature')) {
// Feature logic
}
```
### Promoting a Feature
When a feature is ready for the next stage:
1. **Update [`features.ts`]**: Add a new `FeatureSpec` to the feature's array.
- **To BETA**: Set `preRelease: FeatureStage.Beta` (Defaults to `true`).
- **To GA**: Set `preRelease: FeatureStage.GA` (Defaults to `true` and
locked).
- Update the `since` version.
2. **Update [`settingsSchema.ts`]**: Update the `label` and `description` if
necessary.
3. **GA Cleanup**: Once a feature is GA and no longer optional, remove the
feature gate check from the code and make it a core part of the logic.
### Deprecating a Feature
This stage is for **Beta** and **GA** features scheduled for removal.
1. **Update [`features.ts`]**: Add a new `FeatureSpec` with
`preRelease: FeatureStage.Deprecated`.
- Optionally set `default: true` if it should remain enabled during
deprecation (it defaults to `false`).
- Optionally set an `until` version to indicate when it will be removed.
2. **Update [`settingsSchema.ts`]**: Update the description to notify users of
the deprecation and suggest alternatives.
### Removing a Feature
> **Alpha** features can be removed without formal deprecation. **Beta** and
> **GA** features should typically go through a
> [deprecation period](#deprecating-a-feature) first.
To completely remove a feature:
1. **Cleanup Code**: Remove all logic and tests associated with the feature.
2. **Update [`features.ts`]**: Remove the feature from [`FeatureDefinitions`].
3. **Update [`settingsSchema.ts`]**: Remove the feature from the `features`
object.
4. **Legacy Settings**: If the feature had a legacy `experimental` flag, ensure
its migration logic is cleaned up in [`config.ts`].
## Relevant Documentation
- [Settings Reference]
- [Configuration Layers]
[Configuration guide]: /docs/get-started/configuration.md
[Settings Reference]: /docs/cli/settings.md#features
[Configuration Layers]: /docs/get-started/configuration.md#configuration-layers
[`FeatureDefinitions`]: /packages/core/src/config/features.ts
[`features.ts`]: /packages/core/src/config/features.ts
[`settingsSchema.ts`]: /packages/cli/src/config/settingsSchema.ts
[`config.ts`]: /packages/core/src/config/config.ts
docs/cli/settings.md
+17
View File
@@ -162,4 +162,21 @@ they appear in the UI.
| Enable Hooks | `hooksConfig.enabled` | Canonical toggle for the hooks system. When disabled, no hooks will be executed. | `true` |
| Hook Notifications | `hooksConfig.notifications` | Show visual indicators when hooks are executing. | `true` |
### Features
| UI Label | Setting | Description | Default | Stage |
| ----------------------------- | ------------------------------ | ----------------------------------------------------------- | ------- | ------- |
| Enable all Alpha features | `features.allAlpha` | Enable all Alpha features by default. | `false` | - |
| Enable all Beta features | `features.allBeta` | Enable all Beta features by default. | `true` | - |
| Tool Output Masking | `features.toolOutputMasking` | Enables tool output masking to save tokens. | `true` | `BETA` |
| Enable Agents | `features.enableAgents` | Enable local and remote subagents. | `false` | `ALPHA` |
| Extension Management | `features.extensionManagement` | Enable extension management features. | `true` | `BETA` |
| Extension Configuration | `features.extensionConfig` | Enable requesting and fetching of extension settings. | `true` | `BETA` |
| Extension Registry Explore UI | `features.extensionRegistry` | Enable extension registry explore UI. | `false` | `ALPHA` |
| Extension Reloading | `features.extensionReloading` | Enables extension loading/unloading within the CLI session. | `false` | `ALPHA` |
| JIT Context Loading | `features.jitContext` | Enable Just-In-Time (JIT) context loading. | `false` | `ALPHA` |
| Use OSC 52 Paste | `features.useOSC52Paste` | Use OSC 52 sequence for pasting. | `false` | `ALPHA` |
| Plan Mode | `features.plan` | Enable planning features (Plan Mode and tools). | `false` | `ALPHA` |
| Zed Integration | `features.zedIntegration` | Enable Zed integration. | `false` | `ALPHA` |
<!-- SETTINGS-AUTOGEN:END -->
docs/reference/configuration.md
+91 -3
View File
@@ -83,6 +83,16 @@ contain other project-specific files related to Gemini CLI's operation, such as:
Settings are organized into categories. All settings should be placed within
their corresponding top-level category object in your `settings.json` file.
#### Feature Lifecycle
Gemini CLI uses a feature lifecycle management system to manage experimental and
optional features. Features are categorized by their stability stage (`ALPHA`,
`BETA`, `GA`, `DEPRECATED`).
For a detailed explanation of feature stages and a list of all available
features, see the
[Feature Lifecycle documentation](/docs/cli/feature-lifecycle.md).
<!-- SETTINGS-AUTOGEN:START -->
#### `policyPaths`
@@ -1056,7 +1066,6 @@ their corresponding top-level category object in your `settings.json` file.
`gemma3-1b-gpu-custom`.
- **Default:** `"gemma3-1b-gpu-custom"`
- **Requires restart:** Yes
#### `skills`
- **`skills.enabled`** (boolean):
@@ -1165,6 +1174,77 @@ their corresponding top-level category object in your `settings.json` file.
- **`admin.skills.enabled`** (boolean):
- **Description:** If false, disallows agent skills from being used.
- **Default:** `true`
#### `features`
- **`features.allAlpha`** (boolean):
- **Description:** Enable all Alpha features by default.
- **Default:** `false`
- **Requires restart:** Yes
- **`features.allBeta`** (boolean):
- **Description:** Enable all Beta features by default.
- **Default:** `true`
- **Requires restart:** Yes
- **`features.toolOutputMasking`** (boolean):
- **Description:** Enables tool output masking to save tokens.
- **Default:** `true`
- **Stage:** BETA
- **Requires restart:** Yes
- **`features.enableAgents`** (boolean):
- **Description:** Enable local and remote subagents.
- **Default:** `false`
- **Stage:** ALPHA
- **Requires restart:** Yes
- **`features.extensionManagement`** (boolean):
- **Description:** Enable extension management features.
- **Default:** `true`
- **Stage:** BETA
- **Requires restart:** Yes
- **`features.extensionConfig`** (boolean):
- **Description:** Enable requesting and fetching of extension settings.
- **Default:** `true`
- **Stage:** BETA
- **Requires restart:** Yes
- **`features.extensionRegistry`** (boolean):
- **Description:** Enable extension registry explore UI.
- **Default:** `false`
- **Stage:** ALPHA
- **Requires restart:** Yes
- **`features.extensionReloading`** (boolean):
- **Description:** Enables extension loading/unloading within the CLI session.
- **Default:** `false`
- **Stage:** ALPHA
- **Requires restart:** Yes
- **`features.jitContext`** (boolean):
- **Description:** Enable Just-In-Time (JIT) context loading.
- **Default:** `false`
- **Stage:** ALPHA
- **Requires restart:** Yes
- **`features.useOSC52Paste`** (boolean):
- **Description:** Use OSC 52 sequence for pasting.
- **Default:** `false`
- **Stage:** ALPHA
- **`features.plan`** (boolean):
- **Description:** Enable planning features (Plan Mode and tools).
- **Default:** `false`
- **Stage:** ALPHA
- **Requires restart:** Yes
- **`features.zedIntegration`** (boolean):
- **Description:** Enable Zed integration.
- **Default:** `false`
- **Stage:** ALPHA
- **Requires restart:** Yes
<!-- SETTINGS-AUTOGEN:END -->
#### `mcpServers`
@@ -1350,6 +1430,10 @@ the `advanced.excludedEnvVars` setting in your `settings.json` file.
is useful when running Gemini CLI in a standalone terminal while still
wanting to associate it with a specific IDE instance.
- Overrides the automatic IDE detection logic.
- **`GEMINI_FEATURE_GATES`**:
- Specifies a comma-separated list of feature key-value pairs to override the
default feature states.
- Example: `export GEMINI_FEATURE_GATES="plan=true,enableAgents=false"`
- **`GEMINI_CLI_HOME`**:
- Specifies the root directory for Gemini CLI's user-level configuration and
storage.
@@ -1551,13 +1635,17 @@ for that specific session.
- `auto_edit`: Automatically approve edit tools (replace, write_file) while
prompting for others
- `yolo`: Automatically approve all tool calls (equivalent to `--yolo`)
- `plan`: Read-only mode for tool calls (requires experimental planning to
be enabled).
- `plan`: Read-only mode for tool calls (requires planning feature to be
enabled).
> **Note:** This mode is currently under development and not yet fully
> functional.
- Cannot be used together with `--yolo`. Use `--approval-mode=yolo` instead of
`--yolo` for the new unified approach.
- Example: `gemini --approval-mode auto_edit`
- **`--feature-gates <key1=val1,key2=val2,...>`**:
- A comma-separated list of feature key-value pairs to override the default
feature states for this session.
- Example: `gemini --feature-gates "plan=true,enableAgents=false"`
- **`--allowed-tools <tool1,tool2,...>`**:
- A comma-separated list of tool names that will bypass the confirmation
dialog.