From c4a35898d91601910a7f6c4a45a63f349fccac88 Mon Sep 17 00:00:00 2001 From: Emil Lundmark Date: Thu, 23 Jun 2022 10:15:03 +0200 Subject: [PATCH] Add documentation for field trials Bug: webrtc:14154 Change-Id: I8866933046bb3c673b55fc8edf5fdbff11b60fad Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/266481 Reviewed-by: Artem Titov Reviewed-by: Harald Alvestrand Commit-Queue: Emil Lundmark Cr-Commit-Position: refs/heads/main@{#37309} --- g3doc/field-trials.md | 45 +++++++++++++++++++++++++++++++++++++++++++ g3doc/sitemap.md | 2 ++ 2 files changed, 47 insertions(+) create mode 100644 g3doc/field-trials.md diff --git a/g3doc/field-trials.md b/g3doc/field-trials.md new file mode 100644 index 0000000000..66246dea9d --- /dev/null +++ b/g3doc/field-trials.md @@ -0,0 +1,45 @@ +# Field trials + + + + +WebRTC provides some means to alter its default behavior during run-time, +colloquially known as *field trials*. This is foremost used for A/B testing new +features and are related to +[Chromium field trials](https://chromium.googlesource.com/chromium/src/+/main/testing/variations/README.md) +to facilitate interoperability. + +A field trial consist of a key-value pair of strings. By convention, the field +trial key is prefixed with `WebRTC-` and each word is capitalized without +spaces. Sometimes the key is further subdivided into a category, for example, +`WebRTC-MyCategory-MyExperiment`. The field trial value is an opaque string and +it is up to the author to define what it represents. There are +[helper functions](https://webrtc.googlesource.com/src/+/refs/heads/main/api/field_trials_view.h) +to use a field trial as a boolean, with the string `Enabled` representing true +and `Disabled` representing false. You can also use +[field trial parameters](https://webrtc.googlesource.com/src/+/refs/heads/main/rtc_base/experiments/field_trial_parser.h) +if you wish to encode more elaborate data types. + +The set of field trials can be instantiated from a single string with the format +`////`. Note the final `/` at the end! In +Chromium you can launch with the `--force-fieldtrials` flag to instantiate field +trials this way, for example: + +``` +--force-fieldtrials="WebRTC-Foo/Enabled/WebRTC-Bar/Disabled/" +``` + +## Policy + +The policy for field trials is: + +- A field trial should only be used to test out new code or parameters for a + limited time period. It should not be used for configuring persistent + behavior. +- The field trial must have an end date. The end date may be pushed back if + necessary, but should not be pushed back indefinitely. +- A field trial must be associated with a bug that + - reserves the field trial key, + - is open, + - is assigned to an owner, and + - has the end date specified. diff --git a/g3doc/sitemap.md b/g3doc/sitemap.md index 4a705c4da0..4255531660 100644 --- a/g3doc/sitemap.md +++ b/g3doc/sitemap.md @@ -46,3 +46,5 @@ * Network emulation * [Implementation](/test/network/g3doc/index.md) * Performance stats collection +* Experimentation + * [Field trials](/g3doc/field-trials.md)