75 lines
2.5 KiB
Markdown
75 lines
2.5 KiB
Markdown
# Spec: Feature flags
|
||
|
||
This spec describes how OliveTin opts into unfinished or optional product features for the whole installation.
|
||
|
||
---
|
||
|
||
## 1. Scope
|
||
|
||
Feature flags are **global** settings. They apply to every user and are not overridden by access control lists or policy.
|
||
|
||
They are distinct from policy options such as diagnostics or log list visibility, which may differ per user.
|
||
|
||
All feature-flagged functionality is **alpha / experimental**. Flags default to off. Security advisories and CVEs are not accepted for issues that only affect feature-flagged code; see the project security policy.
|
||
|
||
---
|
||
|
||
## 2. Configuration
|
||
|
||
Flags live under `features` in configuration.
|
||
|
||
- Each flag is a boolean.
|
||
- Omitted flags are **false**.
|
||
- Enabling a feature requires setting it to true explicitly.
|
||
|
||
Example:
|
||
|
||
```yaml
|
||
features:
|
||
headerSearch: true
|
||
```
|
||
|
||
Unknown keys under `features` are ignored by the configuration loader (same as other unknown config keys).
|
||
|
||
---
|
||
|
||
## 3. Init projection
|
||
|
||
Every Init response includes a `features` object with the current flag values.
|
||
|
||
Clients must not assume a missing flag means enabled. Treat absent or false as off.
|
||
|
||
---
|
||
|
||
## 4. Server and client behavior
|
||
|
||
When a feature is off:
|
||
|
||
- The server skips work that exists only to support that feature (for example, building search hints when header search is off).
|
||
- The web UI hides controls and does not index or call APIs that exist only for that feature.
|
||
|
||
When a feature is on, normal access control still applies to the data and actions the feature exposes. Operators who enable a flag accept that the surface is experimental.
|
||
|
||
---
|
||
|
||
## 5. Header search
|
||
|
||
`features.headerSearch` controls the header QuickSearch control and Init search hints.
|
||
|
||
- Default: false (alpha / experimental).
|
||
- When false: Init omits search hints; the client does not show QuickSearch or populate the search index.
|
||
- When true: Init includes ACL-filtered search hints (unless guests must log in); the client shows QuickSearch after login is satisfied.
|
||
|
||
---
|
||
|
||
## 6. Adding a new flag
|
||
|
||
To add a flag:
|
||
|
||
1. Add a boolean field under `features` in configuration (default false).
|
||
2. Add the same field to the Init `features` message.
|
||
3. Project the value on every Init response.
|
||
4. Gate server work and UI behind the flag.
|
||
5. Document the flag as alpha / experimental and update this spec’s feature list.
|
||
6. Keep the security policy statement that CVEs are not accepted for feature-flagged functionality until the feature graduates (flag removed or stable default-on).
|