settings: Add the concept of experimental feature flags

Fixes #1409.

Author: gnprice

assets/l10n/app_en.arb

@@ -823,6 +823,14 @@
   "@pollWidgetOptionsMissing": {
     "description": "Text to display for a poll when it has no options"
   },
+  "experimentalFeatureSettingsPageTitle": "Experimental features",
+  "@experimentalFeatureSettingsPageTitle": {
+    "description": "Title of settings page for experimental, in-development features"
+  },
+  "experimentalFeatureSettingsWarning": "These options enable features which are still under development and not ready. They may not work, and may cause issues in other areas of the app.\n\nThe purpose of these settings is for experimentation by people working on developing Zulip.",
+  "@experimentalFeatureSettingsWarning": {
+    "description": "Warning text on settings page for experimental, in-development features"
+  },
   "errorNotificationOpenTitle": "Failed to open notification",
   "@errorNotificationOpenTitle": {
     "description": "Error title when notification opening fails"

lib/generated/l10n/zulip_localizations.dart

@@ -1203,6 +1203,18 @@ abstract class ZulipLocalizations {
   /// **'This poll has no options yet.'**
   String get pollWidgetOptionsMissing;
 
+  /// Title of settings page for experimental, in-development features
+  ///
+  /// In en, this message translates to:
+  /// **'Experimental features'**
+  String get experimentalFeatureSettingsPageTitle;
+
+  /// Warning text on settings page for experimental, in-development features
+  ///
+  /// In en, this message translates to:
+  /// **'These options enable features which are still under development and not ready. They may not work, and may cause issues in other areas of the app.\n\nThe purpose of these settings is for experimentation by people working on developing Zulip.'**
+  String get experimentalFeatureSettingsWarning;
+
   /// Error title when notification opening fails
   ///
   /// In en, this message translates to:

lib/generated/l10n/zulip_localizations_ar.dart

@@ -643,6 +643,12 @@ class ZulipLocalizationsAr extends ZulipLocalizations {
   @override
   String get pollWidgetOptionsMissing => 'This poll has no options yet.';
 
+  @override
+  String get experimentalFeatureSettingsPageTitle => 'Experimental features';
+
+  @override
+  String get experimentalFeatureSettingsWarning => 'These options enable features which are still under development and not ready. They may not work, and may cause issues in other areas of the app.\n\nThe purpose of these settings is for experimentation by people working on developing Zulip.';
+
   @override
   String get errorNotificationOpenTitle => 'Failed to open notification';
 

lib/generated/l10n/zulip_localizations_en.dart

@@ -643,6 +643,12 @@ class ZulipLocalizationsEn extends ZulipLocalizations {
   @override
   String get pollWidgetOptionsMissing => 'This poll has no options yet.';
 
+  @override
+  String get experimentalFeatureSettingsPageTitle => 'Experimental features';
+
+  @override
+  String get experimentalFeatureSettingsWarning => 'These options enable features which are still under development and not ready. They may not work, and may cause issues in other areas of the app.\n\nThe purpose of these settings is for experimentation by people working on developing Zulip.';
+
   @override
   String get errorNotificationOpenTitle => 'Failed to open notification';
 

lib/generated/l10n/zulip_localizations_ja.dart

@@ -643,6 +643,12 @@ class ZulipLocalizationsJa extends ZulipLocalizations {
   @override
   String get pollWidgetOptionsMissing => 'This poll has no options yet.';
 
+  @override
+  String get experimentalFeatureSettingsPageTitle => 'Experimental features';
+
+  @override
+  String get experimentalFeatureSettingsWarning => 'These options enable features which are still under development and not ready. They may not work, and may cause issues in other areas of the app.\n\nThe purpose of these settings is for experimentation by people working on developing Zulip.';
+
   @override
   String get errorNotificationOpenTitle => 'Failed to open notification';
 

lib/generated/l10n/zulip_localizations_nb.dart

@@ -643,6 +643,12 @@ class ZulipLocalizationsNb extends ZulipLocalizations {
   @override
   String get pollWidgetOptionsMissing => 'This poll has no options yet.';
 
+  @override
+  String get experimentalFeatureSettingsPageTitle => 'Experimental features';
+
+  @override
+  String get experimentalFeatureSettingsWarning => 'These options enable features which are still under development and not ready. They may not work, and may cause issues in other areas of the app.\n\nThe purpose of these settings is for experimentation by people working on developing Zulip.';
+
   @override
   String get errorNotificationOpenTitle => 'Failed to open notification';
 

lib/generated/l10n/zulip_localizations_pl.dart

@@ -643,6 +643,12 @@ class ZulipLocalizationsPl extends ZulipLocalizations {
   @override
   String get pollWidgetOptionsMissing => 'Ta sonda nie ma opcji do wyboru.';
 
+  @override
+  String get experimentalFeatureSettingsPageTitle => 'Experimental features';
+
+  @override
+  String get experimentalFeatureSettingsWarning => 'These options enable features which are still under development and not ready. They may not work, and may cause issues in other areas of the app.\n\nThe purpose of these settings is for experimentation by people working on developing Zulip.';
+
   @override
   String get errorNotificationOpenTitle => 'Otwieranie powiadomienia bez powodzenia';
 

lib/generated/l10n/zulip_localizations_ru.dart

@@ -643,6 +643,12 @@ class ZulipLocalizationsRu extends ZulipLocalizations {
   @override
   String get pollWidgetOptionsMissing => 'В опросе пока нет вариантов ответа.';
 
+  @override
+  String get experimentalFeatureSettingsPageTitle => 'Experimental features';
+
+  @override
+  String get experimentalFeatureSettingsWarning => 'These options enable features which are still under development and not ready. They may not work, and may cause issues in other areas of the app.\n\nThe purpose of these settings is for experimentation by people working on developing Zulip.';
+
   @override
   String get errorNotificationOpenTitle => 'Не удалось открыть оповещения';
 

lib/generated/l10n/zulip_localizations_sk.dart

@@ -643,6 +643,12 @@ class ZulipLocalizationsSk extends ZulipLocalizations {
   @override
   String get pollWidgetOptionsMissing => 'This poll has no options yet.';
 
+  @override
+  String get experimentalFeatureSettingsPageTitle => 'Experimental features';
+
+  @override
+  String get experimentalFeatureSettingsWarning => 'These options enable features which are still under development and not ready. They may not work, and may cause issues in other areas of the app.\n\nThe purpose of these settings is for experimentation by people working on developing Zulip.';
+
   @override
   String get errorNotificationOpenTitle => 'Nepodarilo sa otvoriť oznámenie';
 

lib/model/settings.dart

@@ -58,6 +58,27 @@ enum GlobalSettingType {
   /// (so that it stands ready to accept a future feature flag),
   /// we give it a placeholder value which isn't a real setting.
   placeholder,
+
+  /// Describes a setting which enables an in-progress feature of the app.
+  ///
+  /// Sometimes when building a complex feature it's useful to merge PRs that
+  /// make partial progress, and then to have the feature's logic gated behind
+  /// a setting that serves as a "feature flag".
+  /// This enables those working on the feature to enable the flag in order to
+  /// see the current incomplete behavior, while for everyone else it remains
+  /// disabled and so (barring bugs in the use of the flag itself) has no effect.
+  ///
+  /// These settings are primarily meant for people developing Zulip to use,
+  /// and so appear in an out-of-the-way part of the settings UI.
+  ///
+  /// Settings of this kind are costly to the health of the codebase if
+  /// allowed to accumulate.  Most features don't need one, even features that
+  /// take two or three PRs to implement.  See discussion at:
+  ///   https://github.com/zulip/zulip-flutter/issues/1409#issuecomment-2725793787
+  /// When a feature flag is introduced, take care to drive the project to
+  /// completion, either by merge or removal, so that the flag can be retired
+  /// within a period of a few weeks or months.
+  experimentalFeatureFlag,
   ;
 }
 
@@ -83,6 +104,10 @@ enum GlobalSettingType {
 /// finish an experimental feature.)
 enum BoolGlobalSetting {
   /// A non-setting to ensure this enum has at least one value.
+  ///
+  /// Leave this in place even when there are experimental feature flags too.
+  /// That way when we remove those, this is already here.
+  /// (Having one stable value in this enum is also handy for tests.)
   placeholderIgnore(GlobalSettingType.placeholder, false),
 
   // Former settings which might exist in the database,
@@ -117,6 +142,10 @@ class GlobalSettingsStore extends ChangeNotifier {
     required Map<BoolGlobalSetting, bool> boolData,
   }) : _backend = backend, _data = data, _boolData = boolData;
 
+  static final List<BoolGlobalSetting> experimentalFeatureFlags =
+    BoolGlobalSetting.values.where((setting) =>
+      setting.type == GlobalSettingType.experimentalFeatureFlag).toList();
+
   final GlobalStoreBackend _backend;
 
   /// A cache of the [GlobalSettingsData] singleton in the underlying data store.

lib/widgets/settings.dart

@@ -23,6 +23,11 @@ class SettingsPage extends StatelessWidget {
       body: Column(children: [
         const _ThemeSetting(),
         const _BrowserPreferenceSetting(),
+        if (GlobalSettingsStore.experimentalFeatureFlags.isNotEmpty)
+          ListTile(
+            title: Text(zulipLocalizations.experimentalFeatureSettingsPageTitle),
+            onTap: () => Navigator.push(context,
+              ExperimentalFeaturesPage.buildRoute()))
       ]));
   }
 }
@@ -76,3 +81,31 @@ class _BrowserPreferenceSetting extends StatelessWidget {
       onChanged: (newValue) => _handleChange(context, newValue));
   }
 }
+
+class ExperimentalFeaturesPage extends StatelessWidget {
+  const ExperimentalFeaturesPage({super.key});
+
+  static WidgetRoute<void> buildRoute() {
+    return MaterialWidgetRoute(page: const ExperimentalFeaturesPage());
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final zulipLocalizations = ZulipLocalizations.of(context);
+    final globalSettings = GlobalStoreWidget.settingsOf(context);
+    final flags = GlobalSettingsStore.experimentalFeatureFlags;
+    assert(flags.isNotEmpty);
+    return Scaffold(
+      appBar: AppBar(
+        title: Text(zulipLocalizations.experimentalFeatureSettingsPageTitle)),
+      body: Column(children: [
+        ListTile(
+          title: Text(zulipLocalizations.experimentalFeatureSettingsWarning)),
+        for (final flag in flags)
+          SwitchListTile.adaptive(
+            title: Text(flag.name), // no i18n; these are developer-facing settings
+            value: globalSettings.getBool(flag),
+            onChanged: (value) => globalSettings.setBool(flag, value)),
+      ]));
+  }
+}

test/widgets/settings_test.dart

@@ -126,4 +126,11 @@ void main() {
           ? BrowserPreference.inApp : BrowserPreference.external);
     }, variant: TargetPlatformVariant({TargetPlatform.android, TargetPlatform.iOS}));
   });
+
+  // TODO maybe test GlobalSettingType.experimentalFeatureFlag settings
+  //   Or maybe not; after all, it's a developer-facing feature, so
+  //   should be low risk.
+  //   (The main ingredient in writing such tests would be to wire up
+  //   [GlobalSettingsStore.experimentalFeatureFlags] so that tests can
+  //   control making it empty, or non-empty, at will.)
 }