1# Configuration: Prefs, Settings, Features, Switches & Flags 2 3This document outlines all the runtime configuration surfaces of Chromium, 4and discusses appropriate uses and standard patterns for each of them. Some of 5these are intended for use by users, some by developers, and some by system 6administrators. 7 8## Prefs 9 10Example: prefs::kAllowDinosaurEasterEgg aka "allow_dinosaur_easter_egg" 11 12Prefs are implemented by registering them with a central pref service, usually 13via [Profile::RegisterProfilePrefs][profile-register]. They store typed values, 14which persist across restarts and may be synced between browser instances via 15the Sync service. There are several pref stores, which are documented in detail 16in the [prefs docs][prefs]. They can be directly configured via enterprise 17policy. 18 19Prefs: 20 21* *Are not* directly surfaced to the user 22* *Are not* localized into the user's language 23* *Are* configurable via enterprise policy 24* *Are not* reported via UMA when in use 25* *Are not* included in chrome://version 26* *Are* automatically persistent across restarts (usually) 27 28## Features 29 30Example: base::kDCheckIsFatalFeature 31 32These are implemented via creating a [base::Feature][base-feature] anywhere. 33These can be enabled via server-side experimentation or via the command-line 34using --enable-feature. Which features are in use is tracked by UMA metrics, 35and is visible in chrome://version as the "Variations" field. Do note that in 36release builds, only a series of hashes show up in chrome://version rather than 37the string names of the variations, but these hashes can be turned back into 38string names if needed. This is done by consulting [the testing 39config][fieldtrial-config] for Chromium builds, or a Google-internal tool for 40Chrome builds. 41 42*Features are the best way to add runtime conditional behavior.* 43 44Features: 45 46* *Are not* directly surfaced to the user 47* *Are not* localized into the user's language 48* *Are not* configurable via enterprise policy 49* *Are* reported via UMA/crash when in use 50* *Are* included in chrome://version 51* *Are not* automatically persistent across restarts 52 53## Switches 54 55Example: switches::kIncognito aka "--incognito" 56 57These are implemented by testing anywhere in the codebase for the presence or 58value of a switch in [base::CommandLine::ForCurrentProcess][base-commandline]. 59There is no centralized registry of switches and they can be used for 60essentially any purpose. 61 62Switches: 63 64* *Are not* directly surfaced to the user 65* *Are not* localized into the user's language 66* *Are* configurable via enterprise policy 67* *Are not* reported via UMA when in use 68* *Are* included in chrome://version 69* *Are not* automatically persistent across restarts 70 71In general, switches are inferior to use of base::Feature, which has the same 72capabilities and low engineering overhead but ties into UMA reporting. New code 73should use base::Feature instead of switches. An exception to this is when the 74configuration value is a string, since features can't take an arbitrary string 75value. 76 77## Flags 78 79Example: chrome://flags/#ignore-gpu-blacklist 80 81These are implemented by adding an entry in [about_flags.cc][about-flags] 82describing the flag, as well as metadata in [flag-metadata][flag-metadata]. 83Flags have a name and description, and show up in chrome://flags. Flags also 84have an expiration milestone, after which they will be hidden from that UI and 85disabled, then later removed. Flags are backed by either a feature or a set of 86switches, which they enable at browser startup depending on the value of the 87flag. 88 89Flags should usually be temporary, to allow for pre-launch testing of a feature. 90Permanent flags (those with expiration -1) should only be used when either: 91 92* The flag is regularly used for support/debugging purposes, by asking users to 93 flip it to eliminate a possible problem (such as ignore-gpu-blacklist) 94* The flag is used for ongoing QA/test purposes in environments where command-line 95 switches can't be used (e.g. on mobile) 96 97"Users might need to turn the feature on/off" is not a sufficient justification 98for a permanent flag. If at all possible, we should design features such that 99users don't want or need to turn them off, but if we need to retain that choice, 100we should promote it to a full setting (see below) with translations and 101support. "Developers/QA might need to turn the feature on/off", on the other 102hand, is justification for a permanent flag. 103 104Flags: 105 106* *Are* directly surfaced to the user 107* *Are not* localized into the user's language 108* *Are* configurable via enterprise policy 109* *Are* reported via UMA when in use (via Launch.FlagsAtStartup) 110* *Are not* included in chrome://version 111* *Are* automatically persistent across restarts 112 113## Settings 114 115Example: "Show home button" 116 117Settings are implemented in WebUI, and show up in chrome://settings or one of 118its subpages. They generally are bound to a pref which stores the value of that 119setting. These are comparatively expensive to add, since they require 120localization and some amount of UX involvement to figure out how to fit them 121into chrome://settings, plus documentation and support material. Many settings 122are implemented via prefs, but not all prefs correspond to settings; some are 123used for tracking internal browser state across restarts. 124 125Settings: 126 127* *Are* directly surfaced to the user 128* *Are* localized into the user's language 129* *Are not* configurable via enterprise policy (but their backing prefs may be) 130* *Are not* reported via UMA when in use 131* *Are not* included in chrome://version 132* *Are* automatically persistent across restarts (via their backing prefs) 133 134You should add a setting if end-users might want to change this behavior. A 135decent litmus test for whether something should be a flag or a setting is: "will 136someone who can't read or write code want to change this?" 137 138[base-commandline]: https://cs.chromium.org/chromium/src/base/command_line.h?type=cs&l=98 139[base-feature]: https://cs.chromium.org/chromium/src/base/feature_list.h?sq=package:chromium&g=0&l=53 140[about-flags]: https://cs.chromium.org/chromium/src/chrome/browser/about_flags.cc 141[fieldtrial-config]: https://cs.chromium.org/chromium/src/testing/variations/fieldtrial_testing_config.json 142[flag-metadata]: https://cs.chromium.org/chromium/src/chrome/browser/flag-metadata.json 143[prefs]: https://www.chromium.org/developers/design-documents/preferences 144[profile-register]: https://cs.chromium.org/chromium/src/chrome/browser/profiles/profile.cc?type=cs&g=0&l=138 145