[docs] Update origin trial & feature flag related docs
- Update origin trial docs to explain the relationship between Runtime Enabled Feature & base::Feature - Added more links from each others Change-Id: Id5bd6212093e8ffb66795ffe103dcab34428bcc0 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/3885904 Reviewed-by: Kent Tamura <tkent@chromium.org> Commit-Queue: Ming-Ying Chung <mych@chromium.org> Cr-Commit-Position: refs/heads/main@{#1050114}
This commit is contained in:
Ming-Ying Chung
committed by
Chromium LUCI CQ
Chromium LUCI CQ
parent
ce30c806c6
commit
c23505d6b7
@ -160,10 +160,7 @@ used when committed.
|
||||
* [Ozone Overview](ozone_overview.md) - Ozone is an abstraction layer between
|
||||
the window system and low level input and graphics.
|
||||
* [Optimizing Chrome Web UIs](optimizing_web_uis.md) - Notes on making webuis
|
||||
more performant
|
||||
* [Adding a new feature flag in chrome://flags](how_to_add_your_feature_flag.md) - Quick
|
||||
guide to add a new feature flag to experiment your feature.
|
||||
* [Guidelines for considering branch dates in project planning](release_branch_guidance.md) -
|
||||
more performant* [Guidelines for considering branch dates in project planning](release_branch_guidance.md) -
|
||||
What to do (and not to do) around branch dates when scheduling your project
|
||||
work.
|
||||
* [WebUI Explainer](webui_explainer.md) - An explanation of C++ and JavaScript
|
||||
@ -206,6 +203,14 @@ used when committed.
|
||||
* [Code Coverage in Gerrit](testing/code_coverage_in_gerrit.md) - Per-CL code
|
||||
coverage in Gerrit to assist code reviews.
|
||||
|
||||
### Configuration Docs
|
||||
|
||||
* [Configuration: Prefs, Settings, Features, Switches & Flags](configuration.md) - Explains different ways to gate a new feature.
|
||||
* [Adding a new feature flag in chrome://flags](how_to_add_your_feature_flag.md) - Quick guide to add a new feature flag to experiment your feature.
|
||||
* [Runtime Enabled Features](https://chromium.googlesource.com/chromium/src/+/main/third_party/blink/renderer/platform/RuntimeEnabledFeatures.md)
|
||||
* [Initialization of Blink runtime features in content layer](initialize_blink_features.md)
|
||||
* [Integrating a feature with the origin trials framework](origin_trials_integration.md)
|
||||
|
||||
### GPU-related docs
|
||||
* [GPU Pixel Wrangling](gpu/pixel_wrangling.md) - Instructions for GPU
|
||||
pixel wrangling (the GPU sheriffing rotation).
|
||||
|
||||
@ -5,6 +5,8 @@ and discusses appropriate uses and standard patterns for each of them. Some of
|
||||
these are intended for use by users, some by developers, and some by system
|
||||
administrators.
|
||||
|
||||
[TOC]
|
||||
|
||||
## Prefs
|
||||
|
||||
Example: prefs::kAllowDinosaurEasterEgg aka "allow_dinosaur_easter_egg"
|
||||
@ -135,10 +137,18 @@ You should add a setting if end-users might want to change this behavior. A
|
||||
decent litmus test for whether something should be a flag or a setting is: "will
|
||||
someone who can't read or write code want to change this?"
|
||||
|
||||
## Related Documents
|
||||
|
||||
* [Chromium Feature API & Finch (Googler-only)](http://go/finch-feature-api)
|
||||
* [Adding a new feature flag in chrome://flags](how_to_add_your_feature_flag.md)
|
||||
* [Runtime Enabled Features](../third_party/blink/renderer/platform/RuntimeEnabledFeatures.md)
|
||||
* [Initialization of Blink runtime features in content layer](initialize_blink_features.md)
|
||||
* [Integrating a feature with the origin trials framework](origin_trials_integration.md)
|
||||
|
||||
[base-commandline]: https://cs.chromium.org/chromium/src/base/command_line.h?type=cs&l=98
|
||||
[base-feature]: https://cs.chromium.org/chromium/src/base/feature_list.h?sq=package:chromium&g=0&l=53
|
||||
[about-flags]: https://cs.chromium.org/chromium/src/chrome/browser/about_flags.cc
|
||||
[fieldtrial-config]: https://cs.chromium.org/chromium/src/testing/variations/fieldtrial_testing_config.json
|
||||
[flag-metadata]: https://cs.chromium.org/chromium/src/chrome/browser/flag-metadata.json
|
||||
[prefs]: https://www.chromium.org/developers/design-documents/preferences
|
||||
[profile-register]: https://source.chromium.org/chromium/chromium/src/+/main:chrome/browser/profiles/profile.h;l=189;drc=b0378e4b67a5dbdb15acf0341ccd51acda81c8e0
|
||||
[profile-register]: https://source.chromium.org/chromium/chromium/src/+/main:chrome/browser/profiles/profile.h;l=189;drc=b0378e4b67a5dbdb15acf0341ccd51acda81c8e0
|
||||
|
||||
@ -1,36 +1,68 @@
|
||||
# Adding a new feature flag in chrome://flags
|
||||
|
||||
This document describes how to add your new feature behind a flag. See also
|
||||
[Configuration](configuration.md), which gives more explanation about flags and
|
||||
other options for configuring Chrome.
|
||||
This document describes how to add a new Chrome feature flag visible to users
|
||||
via chrome://flag UI.
|
||||
|
||||
*** note
|
||||
**NOTE:** It's NOT required if you don't intend to make your feature appear in
|
||||
chrome://flag UI.
|
||||
***
|
||||
|
||||
See also the following for definitions:
|
||||
* [Configuration: Features](configuration.md#features)
|
||||
* [Configuration: Flags](configuration.md#flags)
|
||||
|
||||
## Step 1: Adding a new `base::Feature`
|
||||
This step would be different between where you want to use the flag.
|
||||
For example, if you want to use the flag in src/content, you should add a base::Feature to the following files:
|
||||
|
||||
This step would be different depending on where you want to use the flag:
|
||||
|
||||
### To Use the Flag in `content/` Only
|
||||
|
||||
Add a `base::Feature` to the following files:
|
||||
|
||||
* [content/public/common/content_features.cc](https://cs.chromium.org/chromium/src/content/public/common/content_features.cc)
|
||||
* [content/public/common/content_features.h](https://cs.chromium.org/chromium/src/content/public/common/content_features.h)
|
||||
|
||||
If you want to use the flag in blink, you should also read
|
||||
[Runtime Enable Features](https://chromium.googlesource.com/chromium/src/+/main/third_party/blink/renderer/platform/RuntimeEnabledFeatures.md).
|
||||
### To Use the Flag in `third_party/blink/` (and Possibly in `content/`)
|
||||
|
||||
You can refer to [this CL](https://chromium-review.googlesource.com/c/554510/) and [this document](initialize_blink_features.md)
|
||||
to see
|
||||
Add a `base::Feature` to the following files:
|
||||
|
||||
1. where to add the base::Feature
|
||||
[[1](https://chromium-review.googlesource.com/c/554510/8/content/public/common/content_features.cc#253)]
|
||||
[[2](https://chromium-review.googlesource.com/c/554510/8/content/public/common/content_features.h)]
|
||||
2. how to use it
|
||||
[[1](https://chromium-review.googlesource.com/c/554510/8/content/common/service_worker/service_worker_utils.cc#153)]
|
||||
3. how to wire your new base::Feature to a blink runtime feature[[1](https://chromium.googlesource.com/chromium/src/+/main/docs/initialize_blink_features.md)]
|
||||
4. how to use it in blink
|
||||
[[1](https://chromium-review.googlesource.com/c/554510/8/third_party/blnk/renderere/core/workers/worker_thread.cc)]
|
||||
* [third_party/blink/common/features.cc](https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/common/features.cc)
|
||||
* [third_party/blink/public/common/features.h](https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/public/common/features.h)
|
||||
|
||||
Historically, Blink also has its own runtime feature mechanism. So if you
|
||||
feature needs to be runtime-enabled, read also Blink's
|
||||
[Runtime Enable Features][blink-rte] doc and
|
||||
[Initialization of Blink runtime features in content layer][blink-rte-init].
|
||||
|
||||
[blink-rte]: ../third_party/blink/renderer/platform/RuntimeEnabledFeatures.md
|
||||
|
||||
### Examples
|
||||
|
||||
You can refer to [this CL](https://chromium-review.googlesource.com/c/554510/)
|
||||
and [this document](initialize_blink_features.md) to see
|
||||
|
||||
1. Where to add the `base::Feature`:
|
||||
[[1](https://chromium-review.googlesource.com/c/554510/8/content/public/common/content_features.cc#253)]
|
||||
[[2](https://chromium-review.googlesource.com/c/554510/8/content/public/common/content_features.h)]
|
||||
2. How to use it:
|
||||
[[1](https://chromium-review.googlesource.com/c/554510/8/content/common/service_worker/service_worker_utils.cc#153)]
|
||||
3. How to wire your new `base::Feature` to a Blink runtime feature:
|
||||
[[1][blink-rte-init]]
|
||||
4. How to use it in Blink:
|
||||
[[1](https://chromium-review.googlesource.com/c/554510/8/third_party/blnk/renderere/core/workers/worker_thread.cc)]
|
||||
|
||||
Also, this patch added a virtual test for running web tests with the flag.
|
||||
When you add a flag, you can consider to use that.
|
||||
|
||||
[blink-rte-init]: initialize_blink_features.md
|
||||
|
||||
## Step 2: Adding the feature flag to the chrome://flags UI.
|
||||
|
||||
*** promo
|
||||
Googlers: Read also [Chrome Feature Flag in chrome://flags](http/go/finch-feature-api#chrome-feature-flag-in-chromeflags).
|
||||
***
|
||||
|
||||
*** promo
|
||||
**Tip:** Android WebView has its own flag UI. The WebView team recommends adding
|
||||
your features there too if they are supported on WebView. Follow
|
||||
@ -47,7 +79,8 @@ You have to modify these five files in total.
|
||||
* [chrome/browser/flag-metadata.json](https://cs.chromium.org/chromium/src/chrome/browser/flag-metadata.json)
|
||||
|
||||
At first you need to add an entry to __about_flags.cc__,
|
||||
__flag_descriptions.cc__ and __flag_descriptions.h__. After that, try running the following test.
|
||||
__flag_descriptions.cc__ and __flag_descriptions.h__. After that, try running
|
||||
the following test.
|
||||
|
||||
```bash
|
||||
# Build unit_tests
|
||||
@ -58,9 +91,11 @@ autoninja -C out/Default unit_tests
|
||||
./out/Default/bin/run_unit_tests --gtest_filter=AboutFlagsHistogramTest.CheckHistograms
|
||||
```
|
||||
|
||||
That test will ask you to add several entries to enums.xml. After doing so, run `git cl format`
|
||||
which will insert the entries in enums.xml in the correct order and run the tests again.
|
||||
You can refer to [this CL](https://chromium-review.googlesource.com/c/593707) as an example.
|
||||
That test will ask you to add several entries to enums.xml. After doing so, run
|
||||
`git cl format` which will insert the entries in enums.xml in the correct order
|
||||
and run the tests again.
|
||||
You can refer to [this CL](https://chromium-review.googlesource.com/c/593707) as
|
||||
an example.
|
||||
|
||||
Finally, run the following test.
|
||||
|
||||
@ -70,3 +105,10 @@ Finally, run the following test.
|
||||
|
||||
That test will ask you to update the flag expiry metadata in
|
||||
[flag-metadata.json](https://cs.chromium.org/chromium/src/chrome/browser/flag-metadata.json).
|
||||
|
||||
## Related Documents
|
||||
|
||||
* [Chromium Feature API & Finch (Googler-only)](http://go/finch-feature-api)
|
||||
* [Configuration: Prefs, Settings, Features, Switches & Flags](configuration.md)
|
||||
* [Runtime Enabled Features](../third_party/blink/renderer/platform/RuntimeEnabledFeatures.md)
|
||||
* [Initialization of Blink runtime features in content layer](initialize_blink_features.md)
|
||||
|
||||
@ -80,11 +80,7 @@ If your Blink feature has a custom enabler function, add a new entry to
|
||||
will call `wf::EnableNewFeatureX` to disable it only if that
|
||||
`switches::kNewFeatureX` exists on the command line.
|
||||
|
||||
### 4) Controlled by parameters from a field trial:
|
||||
Add your code to the function
|
||||
[SetRuntimeFeaturesFromFieldTrialParams()][SetRuntimeFeaturesFromFieldTrialParams].
|
||||
|
||||
### 5) Combination of the previous options or not covered:
|
||||
### 4) Combination of the previous options or not covered:
|
||||
For example, you Blink feature could be controlled by both a base::Feature and a
|
||||
command line switch. In this case, your custom logic should live here in
|
||||
[`SetCustomizedRuntimeFeaturesFromCombinedArgs()`][SetCustomizedRuntimeFeaturesFromCombinedArgs].
|
||||
@ -103,4 +99,4 @@ command line switch. In this case, your custom logic should live here in
|
||||
[SetCustomizedRuntimeFeaturesFromCombinedArgs]:<https://chromium.googlesource.com/chromium/src/+/HEAD/content/child/runtime_features.cc#487>
|
||||
[SetRuntimeFeaturesFromChromiumFeatures]:<https://chromium.googlesource.com/chromium/src/+/HEAD/content/child/runtime_features.cc#160>
|
||||
[SetRuntimeFeaturesFromCommandLine]:<https://chromium.googlesource.com/chromium/src/+/HEAD/content/child/runtime_features.cc#390>
|
||||
[SetRuntimeFeaturesFromFieldTrialParams]:<https://chromium.googlesource.com/chromium/src/+/HEAD/content/child/runtime_features.cc#448>
|
||||
[SetRuntimeFeaturesFromFieldTrialParams]:<https://chromium.googlesource.com/chromium/src/+/HEAD/content/child/runtime_features.cc#448>
|
||||
|
||||
@ -1,59 +1,87 @@
|
||||
# Integrating a feature with the origin trials framework
|
||||
# Integrating a feature with the Origin Trials framework
|
||||
|
||||
To expose your feature via the origin trials framework, there are a few code
|
||||
To expose your feature via the [Origin Trials framework], there are a few code
|
||||
changes required.
|
||||
|
||||
*** note
|
||||
**WARNING:** This is only available for features implemented in Blink.
|
||||
***
|
||||
|
||||
[TOC]
|
||||
|
||||
## Code Changes
|
||||
|
||||
NOTE: You can land these code changes before requesting to run an origin trial.
|
||||
*** promo
|
||||
**NOTE:** You can land these code changes before requesting to run an origin
|
||||
trial.
|
||||
These code changes make it possible to control a feature via an origin trial,
|
||||
but don't require an origin trial to be approved. For more on the process, see
|
||||
[Running an Origin Trial].
|
||||
***
|
||||
|
||||
### Runtime Enabled Features
|
||||
### Step 1: Add Runtime Enabled Feature in Blink for Origin Trial
|
||||
|
||||
First, you’ll need to configure [runtime\_enabled\_features.json5]. This is
|
||||
explained in the file, but you use `origin_trial_feature_name` to associate your
|
||||
runtime feature flag with a name for your origin trial. The name can be the
|
||||
same as your runtime feature flag, or different. Eventually, this configured
|
||||
name will be used in the origin trials developer console. You can have both
|
||||
`status: experimental` and `origin_trial_feature_name` if you want your feature
|
||||
to be enabled either by using the `--enable-experimental-web-platform-features`
|
||||
flag **or** the origin trial.
|
||||
First, you’ll need to configure [runtime\_enabled\_features.json5]. If you don't
|
||||
have a Blink's [Runtime Enabled Feature] flag yet, you will need to add an entry
|
||||
in this file.
|
||||
|
||||
You will have to change all callers of the no-argument overload of
|
||||
`RuntimeEnabledFeatures::FooEnabled()` to the overload that takes a
|
||||
`const FeatureContext*`. You can pass an `ExecutionContext` here
|
||||
(e.g. using `ExecutionContext::From(ScriptState*)`).
|
||||
The following fields of an entry are relevant:
|
||||
|
||||
You may have a feature that is not available on all platforms, or need to limit
|
||||
the trial to specific platforms. Use `origin_trial_os: [list]` to specify which
|
||||
platforms will allow the trial to be enabled. The list values are case-
|
||||
insensitive, but must match one of the defined `OS_<platform>` macros (see
|
||||
[build_config.h]).
|
||||
- `name`: The name of your runtime enabled feature, e.g. `"MyFeature"`.
|
||||
- `origin_trial_feature_name`: The name of your runtime enabled feature in the
|
||||
origin trial. This can be the same as your runtime feature flag (i.e. `name`
|
||||
field), or different. Eventually, this configured name will be used in the
|
||||
origin trials developer console.
|
||||
- `origin_trial_os`: Specifies a `[list]` of platforms where they will allow the
|
||||
trial to be enabled. The list values are case-insensitive, but must match one
|
||||
of the defined `OS_<platform>` macros (see [build_config.h]).
|
||||
- `base_feature`: Generates a `base::Feature` in the `blink::features`
|
||||
namespace. It helps to control the Origin Trial remotely. See also
|
||||
[Generate a `base::Feature` instance from a Blink Feature][from blink].
|
||||
|
||||
Not specific to Origin Trial:
|
||||
|
||||
- `status`: Controls when the runtime enabled feature is enabled in Blink. See
|
||||
also [the Status table].
|
||||
- `base_feature_status`: Controls when the `base::Feature` defined by
|
||||
`base_feature` is enabled.
|
||||
|
||||
More details are explained in the json5 file and in the above linked doc.
|
||||
|
||||
If the runtime enabled feature flag is [used in C++](#1-in-c), you will have to
|
||||
change all callers of the no-argument overload of
|
||||
`RuntimeEnabledFeatures::MyFeatureEnabled()` to the overload that takes a
|
||||
`const FeatureContext*`. You can pass an `ExecutionContext` here, e.g. using
|
||||
`ExecutionContext::From(ScriptState*)`.
|
||||
|
||||
#### Examples
|
||||
|
||||
Flag name and trial name are the same:
|
||||
```
|
||||
RuntimeEnabledFeature flag name, trial name and `base::Feature` are all the
|
||||
same:
|
||||
|
||||
```json
|
||||
{
|
||||
name: "MyFeature",
|
||||
name: "MyFeature", // Generates `RuntimeEnabledFeatures::MyFeatureEnabled()`
|
||||
origin_trial_feature_name: "MyFeature",
|
||||
base_feature: "MyFeature", // Generates blink::features::kMyFeature
|
||||
status: "experimental",
|
||||
},
|
||||
```
|
||||
Flag name and trial name are different:
|
||||
```
|
||||
|
||||
RuntimeEnabledFeature flag name and trial name are different:
|
||||
|
||||
```json
|
||||
{
|
||||
name: "MyFeature",
|
||||
origin_trial_feature_name: "MyFeatureTrial",
|
||||
base_feature: "MyFeature", // Generates blink::features::kMyFeature
|
||||
status: "experimental",
|
||||
},
|
||||
```
|
||||
|
||||
Trial limited to specific platform:
|
||||
``` json
|
||||
|
||||
```json
|
||||
{
|
||||
name: "MyFeature",
|
||||
origin_trial_feature_name: "MyFeature",
|
||||
@ -63,8 +91,9 @@ Trial limited to specific platform:
|
||||
```
|
||||
|
||||
#### WebView considerations
|
||||
Because WebView is built as part of the `"android"` os target, it is not possible
|
||||
to exclude a trial from WebView if it is enabled on Android.
|
||||
|
||||
Because WebView is built as part of the `"android"` os target, it is not
|
||||
possible to exclude a trial from WebView if it is enabled on Android.
|
||||
|
||||
If the feature under trial can be enabled on WebView alongside other Android
|
||||
platforms, this is preferred.
|
||||
@ -77,105 +106,235 @@ disabled trial names as values.
|
||||
|
||||
See http://crrev.com/c/3733267 for an example of how this can be done.
|
||||
|
||||
### CSS Properties
|
||||
|
||||
You can also run experiment for new CSS properties with origin trial. After you
|
||||
have configured your feature in [runtime\_enabled\_features.json5] as above, head
|
||||
to [css\_properties.json5]. As explained in the file, you use `runtime_flag` to associate
|
||||
the CSS property with the feature you just defined. This will automatically link the CSS
|
||||
property to the origin trial defined in the runtime feature. It will be available
|
||||
in both JavaScript (`Element.style`) and CSS (including `@supports`) when the trial
|
||||
is enabled.
|
||||
|
||||
|
||||
**Example:** [origin-trial-test-property] defines a test css property controlled via
|
||||
runtime feature `OriginTrialsSampleAPI` and subsequently an origin trial named `Frobulate`.
|
||||
|
||||
### Gating Access
|
||||
### Step 2: Gating Access
|
||||
|
||||
Once configured, there are two mechanisms to gate access to your feature behind
|
||||
an origin trial. You can use either mechanism, or both, as appropriate to your
|
||||
feature implementation.
|
||||
|
||||
1. A native C++ method that you can call in Blink code at runtime to expose your
|
||||
feature: `bool RuntimeEnabledFeatures::MyFeatureEnabled(ExecutionContext*)`
|
||||
2. An IDL attribute \[[RuntimeEnabled]\] that you can use to automatically
|
||||
generate code to expose and hide JavaScript methods/attributes/objects.
|
||||
#### 1) In C++
|
||||
|
||||
A native C++ method that you can call in Blink code at runtime to expose your
|
||||
feature:
|
||||
|
||||
```cpp
|
||||
bool RuntimeEnabledFeatures::MyFeatureEnabled(ExecutionContext*)
|
||||
```
|
||||
|
||||
*** note
|
||||
**WARNING:** Your feature implementation must not persist the result of the
|
||||
enabled check. Your code should simply call
|
||||
`RuntimeEnabledFeatures::MyFeatureEnabled(ExecutionContext*)` as often as
|
||||
necessary to gate access to your feature.
|
||||
***
|
||||
|
||||
#### 2-1) In Web IDL
|
||||
|
||||
An IDL attribute \[[RuntimeEnabled]\] that you can use to automatically generate
|
||||
code to expose and hide JavaScript methods/attributes/objects.
|
||||
|
||||
```cpp
|
||||
[RuntimeEnabled=MyFeature]
|
||||
partial interface Navigator {
|
||||
readonly attribute MyFeatureManager myFeature;
|
||||
}
|
||||
```
|
||||
|
||||
**NOTE:** Your feature implementation must not persist the result of the enabled
|
||||
check. Your code should simply call
|
||||
`RuntimeEnabledFeatures::MyFeatureEnabled(ExecutionContext*)` as often as
|
||||
necessary to gate access to your feature.
|
||||
#### 2-2) CSS Properties
|
||||
|
||||
**NOTE:** For CSS properties, you do not need to edit the IDL files, as the exposure
|
||||
on the [CSSStyleDeclaration] is handled at runtime.
|
||||
*** promo
|
||||
**NOTE:** For CSS properties, you do not need to edit the IDL files, as the
|
||||
exposure on the [CSSStyleDeclaration] is handled at runtime.
|
||||
***
|
||||
|
||||
**ISSUE:** In the rare cases where the origin trial token is added via script after
|
||||
the css style declaration, the css property will be enabled and is fully functional,
|
||||
however it will not appear on the [CSSStyleDeclaration] interface, i.e. not accessible
|
||||
in `Element.style`. This issue is tracked in crbug/1041993.
|
||||
You can also run experiment for new CSS properties with origin trial. After you
|
||||
have configured your feature in [runtime\_enabled\_features.json5] as above,
|
||||
head to [css\_properties.json5]. As explained in the file, you use
|
||||
`runtime_flag` to associate the CSS property with the feature you just defined.
|
||||
This will automatically link the CSS property to the origin trial defined in the
|
||||
runtime feature. It will be available in both JavaScript (`Element.style`) and
|
||||
CSS (including `@supports`) when the trial is enabled.
|
||||
|
||||
### Web Feature Counting
|
||||
*** promo
|
||||
**EXAMPLE:** [origin-trial-test-property] defines a test css property controlled
|
||||
via runtime feature `OriginTrialsSampleAPI` and subsequently an origin trial
|
||||
named `Frobulate`.
|
||||
***
|
||||
|
||||
*** note
|
||||
**ISSUE:** In the rare cases where the origin trial token is added via script
|
||||
after the css style declaration, the css property will be enabled and is fully
|
||||
functional, however it will not appear on the [CSSStyleDeclaration] interface,
|
||||
i.e. not accessible in `Element.style`. This issue is tracked in crbug/1041993.
|
||||
***
|
||||
|
||||
### Step 3: Mapping Runtime Enabled Feature to `base::Feature` (optional)
|
||||
|
||||
Given the following example:
|
||||
|
||||
```json
|
||||
{
|
||||
name: "MyFeature",
|
||||
origin_trial_feature_name: "MyFeature",
|
||||
base_feature: "MyFeature",
|
||||
status: "experimental",
|
||||
},
|
||||
```
|
||||
|
||||
```cpp
|
||||
[RuntimeEnabled=MyFeature]
|
||||
interface MyFeatureAPI {
|
||||
readonly attribute bool dummy;
|
||||
}
|
||||
```
|
||||
|
||||
```cpp
|
||||
// third_party/blink/.../my_feature_api.cc
|
||||
bool MyFeatureAPI::ConnectToBrowser() {
|
||||
if (base::FeatureList::IsEnabled(blink::features::kMyFeature) {
|
||||
// Do something
|
||||
}
|
||||
return false;
|
||||
}
|
||||
```
|
||||
|
||||
The above example shows a new feature relies on a `base::Feature` generated from
|
||||
the `base_feature` definition in json file, e.g. `blink::features::kMyFeature`,
|
||||
in addition to the runtime enabled feature flag `MyFeature`.
|
||||
However, their values are not associated.
|
||||
|
||||
In addition, due to the [limitation](#limitations), the runtime enabled feature
|
||||
flag is not available in the browser process **by default**:
|
||||
|
||||
> if you need to know in the browser process whether a feature should
|
||||
> be enabled, then you will have to either have the renderer inform it at
|
||||
> runtime, or else just assume that it's always enabled, and gate access to the
|
||||
> feature from the renderer.
|
||||
|
||||
*** note
|
||||
**TLDR:** Turning on `MyFeature` doesn't automatically turning on
|
||||
`blink::features::kMyFeature`, and vice versa.
|
||||
***
|
||||
|
||||
To mitigate the issue, there are several options:
|
||||
|
||||
#### Option 1: Fully Enabling `base::Feature`, e.g. `kMyFeature`
|
||||
|
||||
And letting Origin Trial decides when your feature (via runtime enabled feature
|
||||
flag `blink::features::MyFeature`) is available, as suggested in the above
|
||||
quote. The `base::Feature` can be enabled via a remote Finch config, or by
|
||||
updating the default value in C++.
|
||||
|
||||
However, after the Origin Trial ends, it will be impossible to ramp up the
|
||||
feature by Finch if the part controlled by `MyFeature` cannot be enabled
|
||||
independently. For example, if you have a new Web API `MyFeatureAPI`, enabling
|
||||
`MyFeature` will just make the IDL available to everyone without the
|
||||
Blink/browser implementation.
|
||||
|
||||
*** note
|
||||
**Example Bug:** https://crbug.com/1360678.
|
||||
***
|
||||
|
||||
#### Option 2: Setting Up a Custom Mapping
|
||||
|
||||
1. Make `MyFeature` depend on `blink::features::kMyFeature` so that the feature
|
||||
is not enabled if `features::kMyFeatures` is not enabled. In
|
||||
[third_party/blink/renderer/core/origin_trials/origin_trial_context.cc](../third_party/blink/renderer/core/origin_trials/origin_trial_context.cc):
|
||||
|
||||
```cpp
|
||||
bool OriginTrialContext::CanEnableTrialFromName(const StringView& trial_name) {
|
||||
...
|
||||
if (trial_name == "MyFeature") {
|
||||
return base::FeatureList::IsEnabled(blink::features::kMyFeatures);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. Add custom relationship for `MyFeature` and `blink::features::kMyFeature` to
|
||||
handle your use case.
|
||||
|
||||
Read
|
||||
[**Determine how your feature is initialized: Depends on the status of a base::Feature**](initialize_blink_features.md#step-2_determine-how-your-feature-is-initialized)
|
||||
first. If the mappings described there don't meet your use case, refer to
|
||||
the following examples.
|
||||
|
||||
In [content/child/runtime_features.cc](https://source.chromium.org/chromium/chromium/src/+/main:content/child/runtime_features.cc):
|
||||
|
||||
```cpp
|
||||
void SetCustomizedRuntimeFeaturesFromCombinedArgs(
|
||||
const base::CommandLine& command_line) {
|
||||
// Example 1: https://bit.ly/configuring-trust-tokens
|
||||
// Example 2: https://crrev.com/c/3878922/14/content/child/runtime_features.cc
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4: Web Feature Counting
|
||||
|
||||
Once the feature is created, in order to run the origin trial you need to track
|
||||
how often users use your feature. You can do it in two ways.
|
||||
|
||||
#### Increment counter in your c++ code.
|
||||
#### Increment counter in your c++ code
|
||||
|
||||
1. Add your feature counter to end of [web\_feature.mojom]:
|
||||
|
||||
```
|
||||
enum WebFeature {
|
||||
// ...
|
||||
kLastFeatureBeforeYours = 1235,
|
||||
// Here, increment the last feature count before yours by 1.
|
||||
kMyFeature = 1236,
|
||||
```cpp
|
||||
enum WebFeature {
|
||||
// ...
|
||||
kLastFeatureBeforeYours = 1235,
|
||||
// Here, increment the last feature count before yours by 1.
|
||||
kMyFeature = 1236,
|
||||
|
||||
kNumberOfFeatures, // This enum value must be last.
|
||||
};
|
||||
```
|
||||
|
||||
kNumberOfFeatures, // This enum value must be last.
|
||||
};
|
||||
```
|
||||
2. Run [update\_use\_counter\_feature\_enum.py] to update the UMA mapping.
|
||||
|
||||
3. Increment your feature counter in c++ code.
|
||||
```c++
|
||||
#include "third_party/blink/renderer/platform/instrumentation/use_counter.h"
|
||||
|
||||
// ...
|
||||
```c++
|
||||
#include "third_party/blink/renderer/platform/instrumentation/use_counter.h"
|
||||
|
||||
if (RuntimeEnabledFeatures::MyFeatureEnabled(context)) {
|
||||
UseCounter::Count(context, WebFeature::kMyFeature);
|
||||
}
|
||||
```
|
||||
// ...
|
||||
|
||||
if (RuntimeEnabledFeatures::MyFeatureEnabled(context)) {
|
||||
UseCounter::Count(context, WebFeature::kMyFeature);
|
||||
}
|
||||
```
|
||||
|
||||
#### Update counter with \[Measure\] IDL attribute
|
||||
|
||||
1. Add \[[Measure]\] IDL attribute
|
||||
```
|
||||
partial interface Navigator {
|
||||
[RuntimeEnabled=MyFeature, Measure]
|
||||
readonly attribute MyFeatureManager myFeature;
|
||||
```
|
||||
|
||||
```cpp
|
||||
partial interface Navigator {
|
||||
[RuntimeEnabled=MyFeature, Measure]
|
||||
readonly attribute MyFeatureManager myFeature;
|
||||
```
|
||||
|
||||
2. The code to increment your feature counter will be generated in V8
|
||||
automatically. But it requires you to follow \[[Measure]\] IDL attribute
|
||||
naming convention when you will add your feature counter to
|
||||
[web\_feature.mojom].
|
||||
```
|
||||
enum WebFeature {
|
||||
// ...
|
||||
kLastFeatureBeforeYours = 1235,
|
||||
// Here, increment the last feature count before yours by 1.
|
||||
kV8Navigator_MyFeature_AttributeGetter = 1236,
|
||||
|
||||
kNumberOfFeatures, // This enum value must be last.
|
||||
};
|
||||
```
|
||||
```cpp
|
||||
enum WebFeature {
|
||||
// ...
|
||||
kLastFeatureBeforeYours = 1235,
|
||||
// Here, increment the last feature count before yours by 1.
|
||||
kV8Navigator_MyFeature_AttributeGetter = 1236,
|
||||
|
||||
kNumberOfFeatures, // This enum value must be last.
|
||||
};
|
||||
```
|
||||
|
||||
### Step 5: Add Web Tests
|
||||
|
||||
When using the \[[RuntimeEnabled]\] IDL attribute, you should add web tests
|
||||
to verify that the V8 bindings code is working as expected. Depending on how
|
||||
your feature is exposed, you'll want tests for the exposed interfaces, as well
|
||||
as tests for script-added tokens. For examples, refer to the existing tests in
|
||||
[origin_trials/webexposed].
|
||||
|
||||
## Limitations
|
||||
|
||||
@ -199,7 +358,7 @@ be enabled, then you will have to either have the renderer inform it at runtime,
|
||||
or else just assume that it's always enabled, and gate access to the feature
|
||||
from the renderer.
|
||||
|
||||
## Testing
|
||||
## Manual Testing
|
||||
|
||||
To test an origin trial feature during development, follow these steps:
|
||||
|
||||
@ -207,17 +366,17 @@ To test an origin trial feature during development, follow these steps:
|
||||
You can generate signed tokens for any origin that you need to help you test,
|
||||
including localhost or 127.0.0.1. Example:
|
||||
|
||||
```
|
||||
tools/origin_trials/generate_token.py http://localhost:8000 MyFeature
|
||||
```
|
||||
```bash
|
||||
tools/origin_trials/generate_token.py http://localhost:8000 MyFeature
|
||||
```
|
||||
|
||||
There are additional flags to generate third-party tokens, set the expiry
|
||||
date, and control other options. See the command help for details (`--help`).
|
||||
For example, to generate a third-party token, with [user subset exclusion]:
|
||||
|
||||
```
|
||||
tools/origin_trials/generate_token.py --is-third-party --usage-restriction=subset http://localhost:8000 MyFeature
|
||||
```
|
||||
```bash
|
||||
tools/origin_trials/generate_token.py --is-third-party --usage-restriction=subset http://localhost:8000 MyFeature
|
||||
```
|
||||
|
||||
2. Copy the token from the end of the output and use it in a `<meta>` tag or
|
||||
an `Origin-Trial` header as described in the [Developer Guide].
|
||||
@ -225,7 +384,8 @@ To test an origin trial feature during development, follow these steps:
|
||||
3. Run Chrome with the test public key by passing:
|
||||
`--origin-trial-public-key=dRCs+TocuKkocNKa0AtZ4awrt9XKH2SQCI6o4FY6BNA=`
|
||||
|
||||
You can also run Chrome with both the test public key and the default public key along side by passing:
|
||||
You can also run Chrome with both the test public key and the default public key
|
||||
along side by passing:
|
||||
`--origin-trial-public-key=dRCs+TocuKkocNKa0AtZ4awrt9XKH2SQCI6o4FY6BNA=,fMS4mpO6buLQ/QMd+zJmxzty/VQ6B1EUZqoCU04zoRU=`
|
||||
|
||||
The `--origin-trial-public-key` switch is not needed with `content_shell`, as it
|
||||
@ -237,8 +397,9 @@ It's also used by Origin Trials unit tests and web tests.
|
||||
If you cannot set command-line switches (e.g., on Chrome OS), you can also
|
||||
directly modify [chrome_origin_trial_policy.cc].
|
||||
|
||||
To see additional information about origin trial token parsing (including reasons
|
||||
for failures, or token names for successful tokens), you can add these switches:
|
||||
To see additional information about origin trial token parsing (including
|
||||
reasons for failures, or token names for successful tokens), you can add these
|
||||
switches:
|
||||
|
||||
`--vmodule=trial_token=2,origin_trial_context=1`
|
||||
|
||||
@ -247,27 +408,30 @@ If you are building with `is_debug=false`, then you will also need to add
|
||||
|
||||
`--enable-logging=stderr`
|
||||
|
||||
## Related Documents
|
||||
|
||||
### Web Tests
|
||||
When using the \[RuntimeEnabled\] IDL attribute, you should add web tests
|
||||
to verify that the V8 bindings code is working as expected. Depending on how
|
||||
your feature is exposed, you'll want tests for the exposed interfaces, as well
|
||||
as tests for script-added tokens. For examples, refer to the existing tests in
|
||||
[origin_trials/webexposed].
|
||||
- [Chromium Feature API & Finch (Googler-only)](http://go/finch-feature-api)
|
||||
- [Configuration: Prefs, Settings, Features, Switches & Flags](configuration.md)
|
||||
- [Runtime Enabled Features](../third_party/blink/renderer/platform/RuntimeEnabledFeatures.md)
|
||||
- [Initialization of Blink runtime features in content layer](initialize_blink_features.md)
|
||||
|
||||
[Origin Trials framework]: http://googlechrome.github.io/OriginTrials/developer-guide.html
|
||||
[Runtime Enabled Features]: ../third_party/blink/renderer/platform/RuntimeEnabledFeatures.md
|
||||
[from blink]: ../third_party/blink/renderer/platform/RuntimeEnabledFeatures.md#generate-a-instance-from-a-blink-feature
|
||||
[the Status table]: ../third_party/blink/renderer/platform/RuntimeEnabledFeatures.md#adding-a-runtime-enabled-feature
|
||||
[build_config.h]: /build/build_config.h
|
||||
[chrome_origin_trial_policy.cc]: /chrome/common/origin_trials/chrome_origin_trial_policy.cc
|
||||
[generate_token.py]: /tools/origin_trials/generate_token.py
|
||||
[Developer Guide]: https://github.com/jpchase/OriginTrials/blob/gh-pages/developer-guide.md
|
||||
[RuntimeEnabled]: /third_party/blink/renderer/bindings/IDLExtendedAttributes.md#RuntimeEnabled_i_m_a_c
|
||||
[origin_trials/webexposed]: /third_party/blink/web_tests/http/tests/origin_trials/webexposed/
|
||||
[runtime\_enabled\_features.json5]: /third_party/blink/renderer/platform/runtime_enabled_features.json5
|
||||
[trial_token_unittest.cc]: /third_party/blink/common/origin_trials/trial_token_unittest.cc
|
||||
[web\_feature.mojom]: /third_party/blink/public/mojom/use_counter/metrics/web_feature.mojom
|
||||
[RuntimeEnabled]: ../third_party/blink/renderer/bindings/IDLExtendedAttributes.md#RuntimeEnabled_i_m_a_c
|
||||
[origin_trials/webexposed]: ../third_party/blink/web_tests/http/tests/origin_trials/webexposed/
|
||||
[runtime\_enabled\_features.json5]: ../third_party/blink/renderer/platform/runtime_enabled_features.json5
|
||||
[trial_token_unittest.cc]: ../third_party/blink/common/origin_trials/trial_token_unittest.cc
|
||||
[web\_feature.mojom]: ../third_party/blink/public/mojom/use_counter/metrics/web_feature.mojom
|
||||
[update\_use\_counter\_feature\_enum.py]: /tools/metrics/histograms/update_use_counter_feature_enum.py
|
||||
[Measure]: /third_party/blink/renderer/bindings/IDLExtendedAttributes.md#Measure_i_m_a_c
|
||||
[css\_properties.json5]: /third_party/blink/renderer/core/css/css_properties.json5
|
||||
[Measure]: ../third_party/blink/renderer/bindings/IDLExtendedAttributes.md#Measure_i_m_a_c
|
||||
[css\_properties.json5]: ../third_party/blink/renderer/core/css/css_properties.json5
|
||||
[origin-trial-test-property]: https://chromium.googlesource.com/chromium/src/+/ff2ab8b89745602c8300322c2a0158e210178c7e/third_party/blink/renderer/core/css/css_properties.json5#2635
|
||||
[CSSStyleDeclaration]: /third_party/blink/renderer/core/css/css_style_declaration.idl
|
||||
[CSSStyleDeclaration]: ../third_party/blink/renderer/core/css/css_style_declaration.idl
|
||||
[Running an Origin Trial]: https://www.chromium.org/blink/origin-trials/running-an-origin-trial
|
||||
[user subset exclusion]: https://docs.google.com/document/d/1xALH9W7rWmX0FpjudhDeS2TNTEOXuPn4Tlc9VmuPdHA/edit#heading=h.myaz1twlipw
|
||||
|
||||
Reference in New Issue
Block a user