android_webview
apps
ash
base
build
build_overrides
buildtools
cc
chrome
chromecast
chromeos
clank
codelabs
components
content
crypto
dbus
device
docs
accessibility
autofill
chromeos
design
enterprise
experiments
fuchsia
gpu
graphics
images
infra
intl
ios
linux
login
mac
media
memory
memory-infra
patterns
privacy
privacy_budget
process
security
speed
speed_metrics
standards
telemetry_extension
testing
transcripts
ui
updater
webapps
website
webui
workflow
DIR_METADATA
OWNERS
README.md
accessibility.md
ad_tagging.md
adding_to_third_party.md
android_accessing_cpp_enums_in_java.md
android_accessing_cpp_features_in_java.md
android_accessing_cpp_switches_in_java.md
android_build_instructions.md
android_cast_build_instructions.md
android_debugging_instructions.md
android_dynamic_feature_modules.md
android_emulator.md
android_isolated_splits.md
android_jni_ownership_best_practices.md
android_logging.md
android_native_libraries.md
android_studio.md
angle_in_chromium.md
api_keys.md
asan.md
atom.md
benchmark_performance_regressions.md
bfcache.md
bitmap_pipeline.md
branch_gardener.md
building_old_revisions.md
callback.md
ccache_mac.md
chrome_browser_design_principles.md
chrome_os_logging.md
chrome_settings.md
chromedriver_status.md
chromeos_build_instructions.md
chromeos_glossary.md
chromium_browser_vs_google_chrome.md
cipd_and_3pp.md
cl_respect.md
cl_tips.md
clang.md
clang_code_coverage_wrapper.md
clang_format.md
clang_gardening.md
clang_sheriffing.md
clang_static_analyzer.md
clang_tidy.md
clang_tool_refactoring.md
clangd.md
clion.md
closure_compilation.md
cocoa_tips_and_tricks.md
code_review_owners.md
code_reviews.md
commit_checklist.md
component_build.md
configuration.md
contributing.md
cq_fault_attribution.md
cr_respect.md
cr_user_manual.md
cross_platform_ui.md
cygwin_dll_remapping_failure.md
dangling_ptr.md
dangling_ptr_guide.md
dbus_mojo_connection_service.md
debugging_with_crash_keys.md
dependencies.md
deterministic_builds.md
disassemble_code.md
documentation_best_practices.md
documentation_guidelines.md
early-hints.md
eclipse.md
emacs.md
erc_irc.md
flag_expiry.md
flag_guarding_guidelines.md
flag_ownership.md
frame_trees.md
gardener.md
gcs_dependencies.md
gdbinit.md
get_the_code.md
git_cookbook.md
git_submodules.md
git_tips.md
google_chrome_branded_builds.md
google_play_services.md
graphical_debugging_aid_chromium_views.md
gwp_asan.md
history_manipulation_intervention.md
how_cc_works.md
how_to_add_your_feature_flag.md
how_to_extend_web_test_framework.md
idn.md
initialize_blink_features.md
inlined_stack_traces.md
installation_at_vmware.md
ios_build_instructions.md
ios_infra.md
ios_voiceover.md
kiosk_mode.md
life_of_a_frame.md
lldbinit.md
mac_arm64.md
mac_build_instructions.md
mac_lld.md
modifying_session_history_serialization.md
modules.md
mojo_and_services.md
mojo_ipc_conversion.md
mojo_testing.md
native_relocations.md
navbar.md
navigation-request-navigation-state.gv
navigation-request-navigation-state.png
navigation.md
navigation_concepts.md
network_traffic_annotations.md
no_sources_assignment_filter.md
orderfile.md
origin_trials_integration.md
ozone_overview.md
parsing_test_results.md
pgo.md
piranha_plant.md
process_model_and_site_isolation.md
profiling.md
profiling_content_shell_on_android.md
proxy_auto_config.md
qtcreator.md
release_branch_guidance.md
render-frame-host-lifecycle-state.gv
render-frame-host-lifecycle-state.png
render_document.md
rust-unsafe.md
rust.md
seccomp_sandbox_crash_dumping.md
servicification.md
session_history.md
sheriff.md
shutdown.md
special_case_urls.md
static_initializers.md
sublime_ide.md
system_hardening_features.md
tab_helpers.md
threading_and_tasks.md
threading_and_tasks_faq.md
threading_and_tasks_testing.md
toolchain_support.md
tour_of_luci_ui.md
tpm_quick_ref.md
translation_screenshots.md
unretained_dangling_ptr_guide.md
unsafe_buffers.md
updating_clang.md
updating_clang_format_binaries.md
use_counter_wiki.md
useful_urls.md
user_data_dir.md
user_data_storage.md
user_handle_mapping.md
vanilla_msysgit_workflow.md
vscode.md
vscode_python.md
webview_policies.md
win_cross.md
win_order_files.md
windows_build_instructions.md
windows_native_window_occlusion_tracking.md
windows_pwa_integration.md
windows_shortcut_and_taskbar_handling.md
windows_split_dll.md
windows_virtual_desktop_handling.md
wmax_tokens.md
working_remotely_with_android.md
writing_clang_plugins.md
extensions
fuchsia_web
gin
google_apis
gpu
headless
infra
internal
ios
ios_internal
ipc
media
mojo
native_client
native_client_sdk
net
pdf
ppapi
printing
remoting
rlz
sandbox
services
signing_keys
skia
sql
storage
styleguide
testing
third_party
tools
ui
url
v8
webkit
.clang-format
.clang-tidy
.clangd
.git-blame-ignore-revs
.gitallowed
.gitattributes
.gitignore
.gitmodules
.gn
.mailmap
.rustfmt.toml
.vpython3
.yapfignore
ATL_OWNERS
AUTHORS
BUILD.gn
CODE_OF_CONDUCT.md
CPPLINT.cfg
CRYPTO_OWNERS
DEPS
DIR_METADATA
LICENSE
LICENSE.chromium_os
OWNERS
PRESUBMIT.py
PRESUBMIT_test.py
PRESUBMIT_test_mocks.py
README.md
WATCHLISTS
codereview.settings

This reverts commit e7f8c2b338
.
Reason for revert: Will consider putting this documentation elsewhere
Original change's description:
> Document WebView flag requirement in flag_guarding_guidelines.md
>
> Bug: None
> Change-Id: I19afe75cb0b2500ca3fb096041549b09d851543c
> Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4387340
> Commit-Queue: Andrew Williams <awillia@chromium.org>
> Reviewed-by: Richard Coles <torne@chromium.org>
> Cr-Commit-Position: refs/heads/main@{#1124759}
Bug: None
Change-Id: I3b9d6a82fa2645615e8b3ae7da63188e5f8dd6b7
No-Presubmit: true
No-Tree-Checks: true
No-Try: true
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4391302
Bot-Commit: Rubber Stamper <rubber-stamper@appspot.gserviceaccount.com>
Commit-Queue: Andrew Williams <awillia@chromium.org>
Cr-Commit-Position: refs/heads/main@{#1124980}
77 lines
4.2 KiB
Markdown
77 lines
4.2 KiB
Markdown
# Chromium Flag Guarding Guidelines
|
||
|
||
This document describes using [`base::Feature`](/base/feature_list.h) flags which
|
||
can be remotely set via a server. This applies to both A/B experiments
|
||
([internal link](http://go/finch101)) (disabled by default) and to kill switches
|
||
([internal link](http://go/finch-killswitch)) (enabled by default).
|
||
|
||
Google maintains its own server which you'll see referenced by its internal name
|
||
Finch. Other embedders can and do run their own server for their products.
|
||
|
||
[TOC]
|
||
|
||
## Goals
|
||
* Prevent large scale outages and reduce the response time latency of outages of
|
||
Chromium and Android WebView
|
||
* Reduce the need for a binary respin to address problems in the field
|
||
* Catch regressions in core product vitals
|
||
|
||
## Non-Goals
|
||
* Require a flag per CL/bug without consideration. This is not scalable. See the
|
||
next section for guidance of when flags should be used.
|
||
* Flag-guarding of ChromeOS-specific features.
|
||
* Add a lot of long-lived server-configurable flags across the code base. New
|
||
flags generated by this proposal should be removed 1-2 milestones after launch.
|
||
* Mandate that all changes be rolled out via server side configurations.
|
||
|
||
## When is a flag required?
|
||
* Every project/feature launch shall use a flag unless it’s not [feasible](#feasible)
|
||
* Every feature going through Launch Process (Note, you do not need a launch bug
|
||
to use a flag)
|
||
* Every feature using origin trials, per existing [guidelines](https://www.chromium.org/blink/origin-trials/running-an-origin-trial/#is-your-feature-ready-to-be-an-origin-trial:~:text=Have%20a%20way%20to%20remotely%20disable%20the%20feature)
|
||
* Every deprecation/addition of web platform APIs
|
||
* Very large structural changes that have very different paths (e.g. navigation
|
||
rewrite in PlzNavigate, networking rewrite in Network Service, Out-of-process
|
||
Rasterization etc.).
|
||
* Refactorings in code paths that have historically been risky or prone to
|
||
accidental breakages should also be treated the same as a new feature.
|
||
* Regardless of whether it is a new feature, refactoring, or bug fix, there is
|
||
no minimum size that dictates whether a flag is required (either for isolated
|
||
CLs or for many CLs that form a project/feature). A one line change with
|
||
potential to impact stability, performance, usability is just as required to use
|
||
a flag as a multi-thousand line feature.
|
||
* {#feasible}If, as a CL author, you are uncertain whether a flag can/should be
|
||
used, talk to the relevant TL/Uber-TL and if still unsure, just use a flag.
|
||
|
||
## When is a flag not required?
|
||
* Targeted/micro performance optimizations: projects like V8/Skia/decoders etc.
|
||
that have their own large correctness and performance test suites to not have to
|
||
use server rollouts since they have large confidence based on their tests
|
||
* Changes to core data structures where it would almost be impossible to
|
||
maintain both worlds (e.g. V8 pointer compression where adding a branch in each
|
||
dereference would not be practical).
|
||
* Features shipped via component updater: if we ship a bad component we can
|
||
update to a fixed one
|
||
* Chrome A/B binary experiments: we can use Omaha/AppStore/Play to update users
|
||
from bad builds
|
||
* Non-chromium-repo binary drops: e.g. SwiftShader
|
||
* Rolling/Updating third party dependencies (e.g. libvpx, libwebp etc.)
|
||
* Mechanical/automated refactorings
|
||
* Changes to internal API naming
|
||
* Simple parameter changes (adding params, changing the type etc.)
|
||
* Isolated refactorings where test coverage with high test coverage / confidence
|
||
|
||
|
||
## What type of flag rollout to use?
|
||
* If a change has the potential to affect performance or memory
|
||
([internal link](http://go/chrome-browser-guiding-metrics)), or you want to
|
||
analyze the impact of the launch on feature-specific metrics, use a
|
||
disabled-by-default base::Feature flag and run an A/B experiment.
|
||
Non-Googler committers will need to work with owners of the code that work at
|
||
Google to launch and monitor the experiment.
|
||
* Otherwise it should be guarded minimally by an enabled-by-default
|
||
base::Feature flag, which can be remotely disabled by a server configuration.
|
||
* For code in blink, this can be as simple as using a
|
||
[Runtime Enabled Feature](/third_party/blink/renderer/platform/RuntimeEnabledFeatures.md),
|
||
which has long been common-practice for new or changed APIs.
|