proposal: Configuration-gating experimental features #1884

New issue

Open

opened 2026-06-29 22:30:01 +00:00 by nex · 1 comment

nex commented

2026-06-29 22:30:01 +00:00

Owner

For a long time now, continuwuity has treated experimental features with an always on approach, meaning everyone gets the most consistent experience when it comes to deploying - no knobs to twiddle with when needing to enable popular unstable features, like sliding sync (at the time).
However, this consistency is not necessarily true. While it is true that all the endpoints will become available just by updating, this does not necessarily mean the implementation is consistent with expectations. Matrix is a huge specification, and unstable features usually rapidly evolve in their proposal until it reaches the final commit period, which can take months, even years.

Tracking all the changes to the stable specification is somewhat easily done by just following the spec releases, which are done semi-annually (if memory serves), and include a comprehensive changelog that allows us to build checklists, like the one in #880.

Tracking changes to unstable proposals is also theoretically just as easy, by just watching PRs on GitHub, or subscribing to their RSS feeds. However, this does not scale, as it's not unusual for servers to implement dozens of active unstable proposals at a time. Additionally, not all changes to unstable proposals are functional ones; there can be entire weeks spent on adjusting phrasing and fixing typos, which can ultimately lead to notification fatigue when subscribed. It's only really when we're alerted to major changes through things like TWIM, or a user complaining about broken functionality, is it that we can go through and re-read proposals. And even then, there might be open review threads on the proposal document that might even lead to further changes being made before they're resolved!

Feasibility of keeping up to date with dozens of unstable features aside, feature-gating is not uncommon in the Matrix ecosystem. Clients typically mirror the feature-gating of their underlying homeserver, via the /versions endpoint, requiring both the client and server support the function. Federation's feature-gating is usually just "does the endpoint exist". But homeservers typically do have configuration options for choosing which unstable features are enabled (from https://matrix.org/ecosystem/servers/: Synapse, Dendrite, Venator). Active server implementations which do not do this gating are Conduit, presumably due to a lack of unstable features to gate, and Tuwunel, inheriting this same approach from conduwuit. Our primary SDK, Ruma, also does feature-gating, as can be seen in our massive feature list in Cargo.toml.

And this doesn't even cover keeping track of which proposals become stable or abandoned, and the changes associated with them.

For this reason, I'm going to propose that we switch to a configuration based feature gating model:

New and existing unstable features should be gated behind options in a configuration section.
All unstable features should default to disabled UNLESS they're in FCP at the time of implementing, or are incredibly unlikely to change in any way that will make an implementation of them stale in the future (like repeatedly happened with simplified sliding sync).
Experimental features should only be removed from this section once they become stable, EVEN IF they are not yet in a spec release, as stable proposals are unlikely to drift far from their original proposal after merge.
Unstable proposals that have pull requests opened SHOULD remain in a draft state themselves - note that a proposal that itself is marked as a WIP/draft is not eligible to progress further, and additionally a merged pull request is not required to meet proposals' implementation requirements.
Users MAY be encouraged to enable unstable features if said unstable feature(s) would support their specific use case or improve their daily UX, and MAY be encouraged by the various sources of documentation (option docstrings, the web documentation, etc).

In short, this means that installing continuwuity will give you the base Matrix experience, and can be optionally extended using potentially unstable extensions to the protocol. By making this an explicit choice, administrators will be more aware of the expected quirks of unstable implementations, and are less likely to end up with a sour taste towards Matrix if the unstable implementation they like doesn't live up to their expectations.

I'm opening this issue primarily to gather feedback and hear community thoughts. The reason conduwuit chose for using this "always on" approach was a fairly admirable one, but I feel we aren't in a position now to continue that approach. Bearing in mind that we currently only advertise four unstable features (although there are several more actually implemented, but are not tracked anywhere(!)), I doubt this change will be major.

For a long time now, continuwuity has treated experimental features with an *always on* approach, meaning everyone gets the most consistent experience when it comes to deploying - no knobs to twiddle with when needing to enable popular unstable features, like sliding sync (at the time). However, this consistency is not necessarily true. While it is true that all the endpoints will become available just by updating, this does not necessarily mean the implementation is consistent with expectations. Matrix is a huge specification, and unstable features usually rapidly evolve in their proposal until it reaches the *final* commit period, which can take months, even years. Tracking all the changes to the stable specification is somewhat easily done by just following the spec releases, which are done semi-annually (if memory serves), and include a comprehensive changelog that allows us to build checklists, like the one in #880. Tracking changes to unstable proposals is also theoretically just as easy, by just watching PRs on GitHub, or subscribing to their RSS feeds. However, this does not scale, as it's not unusual for servers to implement dozens of active unstable proposals at a time. Additionally, not all changes to unstable proposals are functional ones; there can be entire weeks spent on adjusting phrasing and fixing typos, which can ultimately lead to notification fatigue when subscribed. It's only really when we're alerted to major changes through things like TWIM, or a user complaining about broken functionality, is it that we can go through and re-read proposals. And even then, there might be open review threads on the proposal document that might even lead to further changes being made before they're resolved! Feasibility of keeping up to date with dozens of unstable features aside, feature-gating is not uncommon in the Matrix ecosystem. Clients typically mirror the feature-gating of their underlying homeserver, via the /versions endpoint, requiring both the client and server support the function. Federation's feature-gating is usually just "does the endpoint exist". But homeservers typically do have configuration options for choosing which unstable features are enabled (from <https://matrix.org/ecosystem/servers/>: [Synapse](https://element-hq.github.io/synapse/latest/development/experimental_features.html), [Dendrite](https://github.com/element-hq/dendrite/blob/08cac1ccf0a45471132ad24a29e3ec15643675fa/setup/config/config_mscs.go#L6-L10), [Venator](https://timedout.codeberg.page/venator/configuration-reference/experiments.html)). Active server implementations which do not do this gating are Conduit, presumably due to a lack of unstable features to gate, and Tuwunel, inheriting this same approach from conduwuit. Our primary SDK, Ruma, *also* does feature-gating, as can be seen in our [massive feature list in Cargo.toml](https://forgejo.ellis.link/continuwuation/continuwuity/src/commit/5eea8fe8808148c852876d8c6de63148a6ff42f6/Cargo.toml#L348-L383). And this doesn't even cover keeping track of which proposals become stable or abandoned, and the changes associated with them. For this reason, I'm going to propose that we switch to a configuration based feature gating model: * New *and existing* unstable features should be gated behind options in a configuration section. * All unstable features should default to disabled UNLESS they're in FCP at the time of implementing, or are incredibly unlikely to change in any way that will make an implementation of them stale in the future (like repeatedly happened with simplified sliding sync). * Experimental features should only be removed from this section once they become stable, EVEN IF they are not yet in a spec release, as stable proposals are unlikely to drift far from their original proposal after merge. * Unstable proposals that have pull requests opened SHOULD remain in a draft state themselves - note that a proposal that itself is marked as a WIP/draft is not eligible to progress further, and additionally a merged pull request is *not required* to meet proposals' implementation requirements. * Users MAY be encouraged to enable unstable features if said unstable feature(s) would support their specific use case or improve their daily UX, and MAY be encouraged by the various sources of documentation (option docstrings, the web documentation, etc). In short, this means that installing continuwuity will give you the *base* Matrix experience, and can be optionally *extended* using potentially unstable extensions to the protocol. By making this an explicit choice, administrators will be more aware of the expected quirks of unstable implementations, and are less likely to end up with a sour taste towards Matrix if the unstable implementation they like doesn't live up to their expectations. --- I'm opening this issue primarily to gather feedback and hear community thoughts. The reason conduwuit chose for using this "always on" approach was a fairly admirable one, but I feel we aren't in a position now to continue that approach. Bearing in mind that we currently [only advertise four unstable features](https://forgejo.ellis.link/continuwuation/continuwuity/src/commit/5eea8fe8808148c852876d8c6de63148a6ff42f6/src/core/matrix/versions.rs#L33-L44) (although there are several more actually implemented, but are not tracked anywhere(!)), I doubt this change will be *major*.

nex added the

Documentation

Enhancement

Help wanted

Rows
Columns