Source code
Revision control
Copy as Markdown
Other Tools
<!-- go/cmark -->
<!--* freshness: {owner: 'lndmrk' reviewed: '2022-06-23'} *-->
# 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
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
`<key-1>/<value-1>/<key-2>/<value-2>/`. 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, and
- is assigned to an owner.
## Creating a field trial
Before creating a new field trial, make sure to read the [policy](#policy).
Either create a new or reuse an existing bug and make sure it is assigned to the
correct owner. Take note of the bug ID. Next, decide how long you need the field
trial to last. It should be rare to have field trials lasting more than 12
months. You can use the `NextAction` field in the bug to help you remember the
end date.
Using this information, add a new entry to `ACTIVE_FIELD_TRIALS` in
`experiments/field_trials.py`. You may not add new items to
`POLICY_EXEMPT_FIELD_TRIALS` since it is reserved for field trials that were
created before the policy was in place.
## Removing a field trial
Any field trial that has expired or otherwise is not needed anymore may be
removed by following these steps:
- Remove all references from the code base. You can find these by, e.g.
grepping for the field trial key.
- Clean up potential glue code that might have been added.
- Remove the field trial from `ACTIVE_FIELD_TRIALS` in
`experiments/field_trials.py`.
- If all work is finished, also close the associated bug.