# Unstable features policy

Like several other homeservers in the Matrix ecosystem, Continuwuity adopts a "disable by default"
approach to experimental features. This ensures every deployment gets the same baseline stability,
allowing users to opt in to potentially unstable features.

Historically, Continuwuity used maintainer discretion to decide whether an unstable feature should
be enabled by default. However, as the project has grown, and the pace of spec development has
increased, keeping up with unstable proposals becomes less and less feasible by the day, and this
causes the implementation of unstable proposals to gradually drift. This can lead to implementations
becoming so stale they're incompatible, with no bandwidth to get them fixed up.

Continuwuity is already selective about which unstable features it implements: the maintainer team
typically only accept implementations of proposals that seem like they are a net positive for a
large portion of the Matrix ecosystem, rather than aiming to "implement everything". As such, the
unstable feature list should typically be small and manageable.

## Adding an unstable feature

First, navigate to `src/core/config/experiments.rs`. There, you have two options for adding an
experiment to the `Experiments` struct:

1. Use `SimpleExperiment` if the experiment only requires enabling with no further configuration.
2. Define a new struct that implements the `ToggledExperiment` trait.

All experiments must be optional and default to off (i.e. `is_enabled()` returns `false`).
`SimpleExperiment` is actually a wrapper around `Option<bool>`, and the omission of the
configuration OR setting it to `false` disables the experiment. `ToggledExperiment` impls should
copy similar behaviour.

Then, add a public field to the `Experiments` struct that is named the MSC's ID in lowercase.
Add a docstring to it, starting with the proposal title (including ID), then a brief paragraph or
so explaining what the proposal does in simple terms, and then finally end the docstring with a link
to the proposal.

### Advertising support for unstable features

If the proposal requires advertising an unstable feature flag, that flag must be added to
`unstable_features` in `src/core/matrix/versions.rs`. For example:

```diff
pub fn unstable_features(experiments: &Experiments) -> BTreeMap<String, bool> {
	BTreeMap::from_iter([
		// Always enabled feature (https://github.com/matrix-org/matrix-spec-proposals/pull/0000)
		// Expected for spec v1.20
		("org.matrix.msc0000".to_owned(), true),
+		// MSC9999: My Cool Feature (https://github.com/matrix-org/matrix-spec-proposals/pull/9999)
+       ("example.matrix.msc9999".to_owned(), experiments.msc9999.is_enabled())
	])
}
```

This will allow the `/_matrix/client/versions` endpoint to dynamically advertise whether the unstable
feature is enabled on the current server.

## Removing unstable features

If a proposal is abandoned, becomes obsolete, or is accepted into the specification, the unstable
configuration should be removed (and possibly migrated) as soon as possible.

After removing a field from `experiments`, the key should be added to the `DEPRECATED_KEYS` slice in
`src/core/config/mod.rs` (really far down). This will ensure that a warning is printed on startup
when a configuration is using a now-removed config key. For example:

```diff
pub struct Experiments {
-   pub msc9999: SimpleExperiment,
}
```
```diff
const DEPRECATED_KEYS: &[&str] = [
    "foo",
+   "experiments.msc9999",
];
```