From b54e4e3b987f5d33f3799638b5fce20473cec260 Mon Sep 17 00:00:00 2001
From: Will Hunt <2072976+Half-Shot@users.noreply.github.com>
Date: Mon, 16 Mar 2026 09:53:34 +0000
Subject: [PATCH] Update beta documentation (#32757)

* Add missing feature_notification_settings2

* Update beta docs with stronger restrictions

* a note

* Update betas.md

* Update betas.md
---
 docs/betas.md | 41 ++++++++++++++++++++++++++++++++++-------
 docs/labs.md  |  9 ++++++++-
 2 files changed, 42 insertions(+), 8 deletions(-)

diff --git a/docs/betas.md b/docs/betas.md
index e1adb0e604..5f150256a8 100644
--- a/docs/betas.md
+++ b/docs/betas.md
@@ -1,14 +1,41 @@
-# Beta features
+# Beta Features
 
-Beta features are features that are not ready for production yet but the team
-wants more people to try the features and give feedback on them.
+A feature is marked as beta when it is nearly ready for production and the
+team would like to gather wider feedback before turning it on by default.
 
-Before a feature gets into its beta phase, it is often a labs feature (see
-[Labs](https://github.com/element-hq/element-web/blob/develop/docs/labs.md)).
+Betas are visible to all users, [**including** users who have disabled labs settings
+tab](./config.md)
 
-**Be warned! Beta features may not be completely finalised or stable!**
+**Be warned! Beta features are not considered stable and should not be relied upon!**
 
-## Video rooms (`feature_video_rooms`)
+## Requirements
+
+A beta feature MUST first become a labs feature before it can become a beta (see
+[Labs](./labs.md)).
+
+A beta feature MUST have an expected timeline to be upgraded to a stable feature. This timeline
+should not exceed 3 months. If a feature persists in beta for longer and hasn't been explicitly
+extended, the feature MAY be backed out to labs.
+
+A beta feature SHOULD have a rollback path for users to opt-out. If a feature is irreversible or
+could corrupt a user's session or account, it should not be in beta. If this is not possible, it
+MUST be discussed with the team first to devise an alternative strategy.
+
+A beta feature SHOULD have analytics so that the team can understand how many users
+are using it.
+
+## Current Betas
+
+This is the current set of betas enabled in Element Web.
+
+### Video rooms (`feature_video_rooms`)
 
 Enables support for creating and joining video rooms, which are persistent video
 chats that users can jump in and out of.
+
+### New notifications settings (`feature_notification_settings2`) [Beta]
+
+Replaces the legacy notification settings with a new one to manage push rules.
+
+**Warning** This feature has options which are not backwards compatible, disabling
+it may have unintended consequences.
diff --git a/docs/labs.md b/docs/labs.md
index a4ab78b08b..aba48767e0 100644
--- a/docs/labs.md
+++ b/docs/labs.md
@@ -76,7 +76,7 @@ For some sample themes, check out [aaronraimist/element-themes](https://github.c
 
 Enables sharing your current location to the timeline, with live updates.
 
-## Video rooms (`feature_video_rooms`)
+## Video rooms (`feature_video_rooms`) [Beta]
 
 Enables support for creating video rooms, which are persistent video chats that users can jump in and out of.
 
@@ -134,3 +134,10 @@ Encrypt most of the state events in the room, including the room name and topic.
 WARNING: this means that users joining a room who do not have access to its history will not be able to see the name or
 topic of the room, or any other room state information. It also means the room name and topic are not available before
 joining a room.
+
+## New notifications settings (`feature_notification_settings2`) [Beta]
+
+Replaces the legacy notification settings with a new one to manage push rules.
+
+**Warning** This feature has options which are not backwards compatible, disabling
+it may have unintended consequences.