Chromium Docs

Adding a new feature flag in chrome://flags

This document describes how to add a new Chrome feature flag visible to users via chrome://flags UI.

NOTE: It‘s NOT required if you don’t intend to make your feature appear in chrome://flags UI.

See also the following for definitions:

Step 1: Adding a new base::Feature

This step would be different depending on where you want to use the flag:

To use the Flag in content/ and its embedders

Add a base::Feature to the following files:

To use the Flag in content/ Only

Add a base::Feature to the following files:

To Use the Flag in third_party/blink/ (and Possibly in content/)

Add a base::Feature to the following files:

Historically, Blink also has its own runtime feature mechanism. So if you feature needs to be runtime-enabled, read also Blink's Runtime Enable Features doc and Initialization of Blink runtime features in content layer.

Examples

You can refer to this CL and this document to see

  1. Where to add the base::Feature: [1] [2]
  2. How to use it: [1]
  3. How to wire your new base::Feature to a Blink runtime feature: [1]
  4. How to use it in Blink: [1]

Also, this patch added a virtual test for running web tests with the flag. When you add a flag, you can consider to use that.

Step 2: Adding the feature flag to the chrome://flags UI.

Googlers: Read also Chrome Feature Flag in chrome://flags.
Tip: Android WebView has its own flag UI. The WebView team recommends adding your features there too if they are supported on WebView. Follow these steps for WebView flags.

You have to modify these five files in total.

At first you need to add an entry to about_flags.cc, flag_descriptions.cc and flag_descriptions.h. After that, try running the following script which will update enums.xml:

# Updates enums.xml
./tools/metrics/histograms/generate_flag_enums.py --feature <your awesome feature>
# Run AboutFlagsHistogramTest.CheckHistograms to verify enums.xml
./out/Default/unit_tests --gtest_filter=AboutFlagsHistogramTest.CheckHistograms
# Run AboutFlagsHistogramTest.CheckHistograms on Android to verify enums.xml
./out/Default/bin/run_unit_tests --gtest_filter=AboutFlagsHistogramTest.CheckHistograms
NOTE: If CheckHistograms returns an error, it will ask you to add several entries to enums.xml. After doing so, run git cl format which will insert the entries in enums.xml in the correct order and run the tests again. You can refer to this CL as an example.

Finally, run the following test.

./out/Default/unit_tests --gtest_filter=AboutFlagsTest.EveryFlagHasMetadata

That test will ask you to update the flag expiry metadata in flag-metadata.json.

Removing the feature flag.

When a feature flag is no longer used it should be removed. Once it has reached it's final state it can be removed in stages.

First remove the flag from the UI:

Once there is no way to change the flag value, it's usage can be removed from the code.

Finally, once the flag is no longer referenced, it can be removed from content/ and third_party/blink/

Related Documents