Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 70 insertions, 0 deletions

diff --git a/third_party/libwebrtc/g3doc/field-trials.md b/third_party/libwebrtc/g3doc/field-trials.md
new file mode 100644
index 0000000000..724a302fe1
--- /dev/null
+++ b/third_party/libwebrtc/g3doc/field-trials.md
@@ -0,0 +1,70 @@
+<!-- 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
+[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
+`<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.