Update documentation: use base::Features instead of DevTools experiments

Bug: none
Change-Id: I34240f5ad7f29066301ccdfba5d011ccf08a5fd4
Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/6316797
Reviewed-by: Changhao Han <[email protected]>
Auto-Submit: Wolfgang Beyer <[email protected]>
Commit-Queue: Changhao Han <[email protected]>

Author: wolfib

docs/contributing/settings-experiments-features.md

@@ -1,13 +1,85 @@
 # Settings, Experiments, and Features in Chromium DevTools
 
 From a developers perspective the Chromium DevTools experience can be
-customized in three ways: via Settings\>Preferences, Settings\>Experiments,
-or by passing a command line flag to Chromium.
+customized in multiple ways:
+
+* via Settings \> Preferences,
+* via Settings \> Experiments,
+* via `chrome://flags`,
+* or by passing a command line flag to Chromium.
+
+Adding new DevTools experiments is deprecated, the preferred way for adding new
+features / exposing experimental features is via `base::Feature`s. These are
+controllable via Chromium command line parameters or optionally via `chrome://flags`.
+
 
 [TOC]
 
+## How to add `base::Feature` feature flags
+
+[go/chrome-devtools:command-line-config](http://go/chrome-devtools:command-line-config)
+
+`base::Feature`s are defined in the Chromium repository and made available to
+DevTools via host bindings. This allows configuring features which have both a
+DevTools front-end and a Chromium back-end component from a single source of
+truth. But front-end-only features can be controlled via a `base::Feature` just
+as well.
+
+By default, `base::Feature`s are configurable via command line parameters when
+launching Chromium. Optionally, they can be made available via the `chrome://flags`
+UI as well.
+
+### Define a new `base::Feature`
+
+Add a new `base::Feature` to DevTools' [`features.cc`](https://crsrc.org/c/chrome/browser/devtools/features.cc). This feature will automatically be available as a Chrome command line parameter:
+
+```cxx
+// in browser_features.cc
+
+BASE_FEATURE(kDevToolsNewFeature, "DevToolsNewFeature",
+             base::FEATURE_DISABLED_BY_DEFAULT);
+
+// Optionally add feature parameters
+const base::FeatureParam<std::string> kDevToolsNewFeatureStringParam{
+    &kDevToolsNewFeature, "string_param", /*default_value=*/""};
+const base::FeatureParam<double> kDevToolsNewFeatureDoubleParam{
+    &kDevToolsNewFeature, "double_param", /*default_value=*/0};
+
+```
+
+Start Chrome via command line including flags:
+
+```
+out/Default/chrome --enable-features=DevToolsNewFeature
+```
+
+You can even pass additional feature parameters:
+
+```
+out/Default/chrome --enable-features="DevToolsNewFeature:string_param/foo/double_param/0.5"
+```
+
+### Make the `base::Feature` available via `chrome://flags`
+
+This step is optional. If you want the `base::Feature` to be controllable via the `chrome://flags` UI and not only via the command line, follow [this documentation](https://chromium.googlesource.com/chromium/src/+/main/docs/how_to_add_your_feature_flag.md#step-2_adding-the-feature-flag-to-the-chrome_flags-ui).
+
+### Add the new feature to the host configuration being sent to DevTools
+
+ Add the new feature to `DevToolsUIBindings::GetHostConfig` ([link to code](https://crsrc.org/c/chrome/browser/devtools/devtools_ui_bindings.cc;l=1506;drc=dd0b2a0bee86088ec0d481bd8722c06edaaba4a4), [example CL](https://crrev.com/c/5625935)).
+
+### In DevTools, use the new property added to HostConfig
+
+* Update the type definition in [`Runtime.ts`](https://crsrc.org/c/third_party/devtools-frontend/src/front_end/core/root/Runtime.ts).
+* Update the dummy value returned by `getHostConfig` in [`InspectorFrontendHost.ts`](https://crsrc.org/c/third_party/devtools-frontend/src/front_end/core/host/InspectorFrontendHost.ts).
+* Access the host config via `Root.Runtime.hostConfig`.
+* In unit tests, make sure to assign the expected configuration using `updateHostConfig({ foo: bar })`.
+
+Please refer to this [example CL](https://crrev.com/c/5626314).
+
 ## How to add experiments
 
+Note: Adding new DevTools experiments is deprecated, please use a `base::Feature` instead.
+
 If you want to launch a new feature in DevTools behind an experiment flag, you
 will need to do two things:
 
@@ -81,59 +153,3 @@ if(Root.Runtime.experiments.isEnabled('yourExperimentNameHere')) {
    // Experiment code here
 }
 ```
-
-## How to add command line flags
-
-[go/chrome-devtools:command-line-config](http://go/chrome-devtools:command-line-config)
-
-In some situations it would be convenient (or is even necessary) to configure
-DevTools directly via the command line interface (CLI). This is particularly
-useful for features which have both a DevTools front-end and a Chromium back-end
-component, and allows configuration from a single source of truth. For live
-demos of features which are still under development, this can be very helpful
-as well. Presenters would have peace of mind, knowing that their feature is
-working correctly, as long as they are re-using the right command to launch
-Chromium.
-
-### Define a new `base::Feature`
-
-Add a new `base::Feature` to DevTools' [`features.cc`](https://crsrc.org/c/chrome/browser/devtools/features.cc). This feature will automatically be available as a Chrome command line parameter:
-
-```cxx
-// in browser_features.cc
-
-BASE_FEATURE(kDevToolsNewFeature, "DevToolsNewFeature",
-             base::FEATURE_DISABLED_BY_DEFAULT);
-
-// Optionally add feature parameters
-const base::FeatureParam<std::string> kDevToolsNewFeatureStringParam{
-    &kDevToolsNewFeature, "string_param", /*default_value=*/""};
-const base::FeatureParam<double> kDevToolsNewFeatureDoubleParam{
-    &kDevToolsNewFeature, "double_param", /*default_value=*/0};
-
-```
-
-Start Chrome via command line including flags:
-
-```
-out/Default/chrome --enable-features=DevToolsNewFeature
-```
-
-You can even pass additional feature parameters:
-
-```
-out/Default/chrome --enable-features="DevToolsNewFeature:string_param/foo/double_param/0.5"
-```
-
-### Add the new feature to the host configuration being sent to DevTools
-
- Add the new feature to `DevToolsUIBindings::GetHostConfig` ([link to code](https://crsrc.org/c/chrome/browser/devtools/devtools_ui_bindings.cc;l=1506;drc=dd0b2a0bee86088ec0d481bd8722c06edaaba4a4), [example CL](https://crrev.com/c/5625935)).
-
-### In DevTools, use the new property added to HostConfig
-
-* Update the type definition in [`Runtime.ts`](https://crsrc.org/c/third_party/devtools-frontend/src/front_end/core/root/Runtime.ts).
-* Update the dummy value returned by `getHostConfig` in [`InspectorFrontendHost.ts`](https://crsrc.org/c/third_party/devtools-frontend/src/front_end/core/host/InspectorFrontendHost.ts).
-* Access the host config via `Root.Runtime.hostConfig`.
-* In unit tests, make sure to assign the expected configuration using `updateHostConfig({ foo: bar })`.
-
-Please refer to this [example CL](https://crrev.com/c/5626314).