Add an initial "Using feature flags" doc for the team. #170767

matanlurey · 2025-06-17T22:21:56Z

There are still some TODOs I'd like to address, but in follow-up PRs:

Update the # Framework sub-sections after Add feature flags to the framework #168437 merges
Add known limitations (i.e. embedder/engine)
Add best practices (using a feature flag versus just using a parameter, named constructor, etc)

jtmcdole · 2025-06-17T22:26:18Z

docs/contributing/Feature-flags.md

+- **Allow experimental access** to features not ready for broad or unguarded
+  use.
+
+  We do not consider it a breaking change to modify or remove experimental flags


We do not consider changes guarded by experimental flags to be breaking either. These features are experimental - we are seeking feedback.

+1, this is a major point that I hope our users will be aware of. The APIs guarded by a feature flag can change at any time and any breakages caused will not be treated as a breaking change.

Also as a nit on the wording here, I think removing an experimental flag could be a breaking change in the context of launching a feature and removing its experimental status and thus the flag. I agree that removing a flag and its feature should not be considered breaking.

Done, tweaked language - PTAL.

jtmcdole · 2025-06-17T22:36:59Z

docs/contributing/Feature-flags.md

+);
+```
+
+### Removing a flag


Do we want to have guidance around the lifetime of the flag:

File an issue describing the flagged experiment

Track when the flags are getting promoted (maybe labels that we could automate)

Track when a flag should be removed

Its also a place for any reports to link back to if they are filed.

We don't have that process today, so I'd prefer not to write about a process that doesn't exist.

(This doc is intending to reflect the current state)

In general +1 having such a process, let's just not conflate it with this code review :)

justinmc

LGTM 👍 A bunch of nits and a few questions but overall this looks great. Thanks for writing a guide for this.

justinmc · 2025-06-17T22:42:43Z

docs/contributing/Feature-flags.md

+Feature flags allow conditionally, consistently, and covenentiantly change
+behavior.


I think a word is missing here.

Also, spelling on "conveniently".

Tweaked, I meant changing.

justinmc · 2025-06-17T22:45:31Z

docs/contributing/Feature-flags.md

+- **Allow experimental access** to features not ready for broad or unguarded
+  use.
+
+  We do not consider it a breaking change to modify or remove experimental flags


+1, this is a major point that I hope our users will be aware of. The APIs guarded by a feature flag can change at any time and any breakages caused will not be treated as a breaking change.

justinmc · 2025-06-17T22:48:19Z

docs/contributing/Feature-flags.md

+- **Allow experimental access** to features not ready for broad or unguarded
+  use.
+
+  We do not consider it a breaking change to modify or remove experimental flags


Also as a nit on the wording here, I think removing an experimental flag could be a breaking change in the context of launching a feature and removing its experimental status and thus the flag. I agree that removing a flag and its feature should not be considered breaking.

justinmc · 2025-06-17T22:50:17Z

docs/contributing/Feature-flags.md

+   Additional parameters are required to make the flag configurable outside of
+   a unit test.


What is this in reference to? Is it really possible to use a feature flag in a unit test without using flutter config or pubspec.yaml?

Ok I see it in the next section. Maybe reference the next section here? Not necessary, though.

Added a (#tests) link to make it a bit more clear.

justinmc · 2025-06-17T22:51:03Z

docs/contributing/Feature-flags.md

+   }
+   ```
+
+1. Add an implement the same getter in [`FlutterFeatureFlagsIsEnabled`][]:


"an" => "and"

Changed to just Implement the...

justinmc · 2025-06-17T22:53:23Z

docs/contributing/Feature-flags.md

+Once a flag is ready to be enabled by default, once again it can be configured
+on a per-channel basis.
+
+For example, enabled on `master` by default, but disabled elsewhere:


Nit: "disabled elsewhere" => "disabled by default elsewhere"

justinmc · 2025-06-17T22:54:35Z

docs/contributing/Feature-flags.md

+refactored and removed from the codebase, and there is less of a possibility of
+conflicting flags.
+
+To a remove a flag, follow the opposite steps of


Extra "a" here.

justinmc · 2025-06-17T22:58:26Z

docs/contributing/Feature-flags.md

+class WebDevices extends PollingDeviceDiscovery {
+  WebDevices({required FeatureFlags featureFlags}) : _featureFlags = featureFlags;


Is this example intending to show that WebDevices itself is the new experimental user-facing feature, and any user wanting to use it needs to use the "globals" pattern mentioned below in order to pass in FeatureFlags? If the feature flag is off then WebDevices does nothing?

Or maybe I'm thrown off by this being in the tool.

No, the intent is that larger-scoped features (like discovery of web devices) might be better suited to take a FeatureFlags instance instead of relying on the global scope. I can make that a bit more clear.

justinmc · 2025-06-17T23:00:54Z

docs/contributing/Feature-flags.md

+
+### Tool
+
+Feature flags can be accessed either by adding (and providing) an explicit


Nit: Maybe be redundant here and say "In the Flutter tool, feature flags...". I'm thinking to avoid people skimming this and copying this code to the wrong place.

Same for below in the framework section.

justinmc

Meant to approve 😄

matanlurey · 2025-06-18T18:38:24Z

I am going to submit this as a draft, and get that flutter.dev/to/ link working, and we can iterate as Loic's PR drops.

…er/flutter#170767)

Roll Flutter from 8303a96 to 85a9b4f (93 revisions) flutter/flutter@8303a96...85a9b4f 2025-06-19 engine-flutter-autoroll@skia.org Roll Skia from af242598f14d to 794936b23812 (2 revisions) (flutter/flutter#170875) 2025-06-19 gourabkumarsi@google.com Drop support for 21/22 Lollipop (flutter/flutter#170748) 2025-06-19 engine-flutter-autoroll@skia.org Roll Dart SDK from 6020126c10e8 to bce9abe03175 (1 revision) (flutter/flutter#170872) 2025-06-19 engine-flutter-autoroll@skia.org Roll Skia from df97f7f407db to af242598f14d (4 revisions) (flutter/flutter#170867) 2025-06-19 engine-flutter-autoroll@skia.org Roll Skia from 1d8f7ebd23cc to df97f7f407db (5 revisions) (flutter/flutter#170864) 2025-06-19 engine-flutter-autoroll@skia.org Roll Dart SDK from 4ab716b09e9d to 6020126c10e8 (1 revision) (flutter/flutter#170862) 2025-06-19 engine-flutter-autoroll@skia.org Roll Skia from 291d41414fa7 to 1d8f7ebd23cc (2 revisions) (flutter/flutter#170857) 2025-06-19 engine-flutter-autoroll@skia.org Roll Dart SDK from b32559bca3cc to 4ab716b09e9d (9 revisions) (flutter/flutter#170855) 2025-06-19 jessy.yameogo@gmail.com remove --start-paused flag by default and set useDwdsWebSocketConnect… (flutter/flutter#170612) 2025-06-18 matanlurey@users.noreply.github.com Engine builders no longer require `is_fusion` (flutter/flutter#170849) 2025-06-18 engine-flutter-autoroll@skia.org Roll Skia from 5f110d5f48a3 to 291d41414fa7 (2 revisions) (flutter/flutter#170836) 2025-06-18 robert.ancell@canonical.com Use a shared vertex buffer for rendering layers. (flutter/flutter#170717) 2025-06-18 30870216+gaaclarke@users.noreply.github.com fixes deeplinking in uiscenedelegate migrated projects (flutter/flutter#170452) 2025-06-18 jonahwilliams@google.com [Impeller] fix array uniforms on GLES backend. (flutter/flutter#170710) 2025-06-18 chinmaygarde@google.com [Impeller] Update README to add section about custom embedders. (flutter/flutter#170077) 2025-06-18 jason-simmons@users.noreply.github.com Escape the forbidden strings in the regex used to check test command output (flutter/flutter#170702) 2025-06-18 30870216+gaaclarke@users.noreply.github.com License cpp jun16 (flutter/flutter#170716) 2025-06-18 chinmaygarde@google.com Work around newer compilers requiring the satisfaction of three-way comparison of EncodableValue. (flutter/flutter#170822) 2025-06-18 45459898+RamonFarizel@users.noreply.github.com Update didUnmountRenderObject text description (flutter/flutter#169628) 2025-06-18 engine-flutter-autoroll@skia.org Roll Skia from 297dbc32a6c7 to 5f110d5f48a3 (2 revisions) (flutter/flutter#170821) 2025-06-18 matanlurey@users.noreply.github.com Add an initial "Using feature flags" doc for the team. (flutter/flutter#170767) 2025-06-18 34465683+rkishan516@users.noreply.github.com Feat: Add mouse cursor for CupertinoDialogAction (flutter/flutter#169051) 2025-06-18 matanlurey@users.noreply.github.com Update `Engine-artifacts.md` to reflect flutter/cocoon/4785 (flutter/flutter#170751) 2025-06-18 alex.medinsh@gmail.com `CupertinoPicker` new onChanged behaviour (flutter/flutter#170202) 2025-06-18 pateltirth454@gmail.com Rename `entryPointBaseUrl` to `entrypointBaseUrl` (flutter/flutter#170166) 2025-06-18 engine-flutter-autoroll@skia.org Roll Skia from 1cb13a21b547 to 297dbc32a6c7 (4 revisions) (flutter/flutter#170809) 2025-06-18 engine-flutter-autoroll@skia.org Roll Packages from 25d4fa4 to 715a0a5 (2 revisions) (flutter/flutter#170808) 2025-06-18 engine-flutter-autoroll@skia.org Roll Skia from 0a106c038cd0 to 1cb13a21b547 (1 revision) (flutter/flutter#170801) 2025-06-18 derekx@google.com Add `--profile-microtasks` switch (flutter/flutter#170690) 2025-06-18 engine-flutter-autoroll@skia.org Roll Skia from ff7fffa5dac5 to 0a106c038cd0 (3 revisions) (flutter/flutter#170795) 2025-06-18 87239766+thakaredipali@users.noreply.github.com Add example for CupertinoExpansionTile transition modes (flutter/flutter#170335) 2025-06-18 stanleycocoa@gmail.com feat: Add radius to DividerThemeData. (flutter/flutter#169739) 2025-06-18 engine-flutter-autoroll@skia.org Roll Skia from 75af9450b121 to ff7fffa5dac5 (3 revisions) (flutter/flutter#170772) 2025-06-17 98614782+auto-submit[bot]@users.noreply.github.com Reverts "add run_gradle_lock_files_check.dart for new PR's that modify gradle files (#169245)" (flutter/flutter#170770) 2025-06-17 30870216+gaaclarke@users.noreply.github.com Started bridging the scene delegate to the lifecycle delegate for shortcuts (flutter/flutter#170180) 2025-06-17 jonahwilliams@google.com [ui] npot display_list allocation. (flutter/flutter#170447) 2025-06-17 kevmoo@users.noreply.github.com Prefer .of over .from (flutter/flutter#170750) 2025-06-17 47866232+chunhtai@users.noreply.github.com Fix RawGestureDetector semantics (flutter/flutter#170549) 2025-06-17 runar@socialscreen.no Use correct type for filterIdentifier (flutter/flutter#170343) 2025-06-17 matanlurey@users.noreply.github.com Remove and inline `license_header.txt` (flutter/flutter#170475) 2025-06-17 muhatashim@google.com add run_gradle_lock_files_check.dart for new PR's that modify gradle files (flutter/flutter#169245) 2025-06-17 engine-flutter-autoroll@skia.org Roll Dart SDK from 4fad61257b29 to b32559bca3cc (3 revisions) (flutter/flutter#170746) 2025-06-17 kevinjchisholm@google.com [release] Sync stable changelog to master (flutter/flutter#170691) 2025-06-17 engine-flutter-autoroll@skia.org Roll Packages from 03a6abb to 25d4fa4 (5 revisions) (flutter/flutter#170743) 2025-06-17 bkonyi@google.com [ Widget Preview ] Remove support for synthetic package:flutter_gen (flutter/flutter#170602) 2025-06-17 engine-flutter-autoroll@skia.org Roll Skia from 8879db3b3319 to 75af9450b121 (4 revisions) (flutter/flutter#170739) ...

Closes flutter#170456. There are still some TODOs I'd like to address, but in follow-up PRs: - Update the `# Framework` sub-sections after flutter#168437 merges - Add known limitations (i.e. embedder/engine) - Add best practices (using a feature flag versus just using a parameter, named constructor, etc)

Roll Flutter from 8303a96 to 85a9b4f (93 revisions) flutter/flutter@8303a96...85a9b4f 2025-06-19 engine-flutter-autoroll@skia.org Roll Skia from af242598f14d to 794936b23812 (2 revisions) (flutter/flutter#170875) 2025-06-19 gourabkumarsi@google.com Drop support for 21/22 Lollipop (flutter/flutter#170748) 2025-06-19 engine-flutter-autoroll@skia.org Roll Dart SDK from 6020126c10e8 to bce9abe03175 (1 revision) (flutter/flutter#170872) 2025-06-19 engine-flutter-autoroll@skia.org Roll Skia from df97f7f407db to af242598f14d (4 revisions) (flutter/flutter#170867) 2025-06-19 engine-flutter-autoroll@skia.org Roll Skia from 1d8f7ebd23cc to df97f7f407db (5 revisions) (flutter/flutter#170864) 2025-06-19 engine-flutter-autoroll@skia.org Roll Dart SDK from 4ab716b09e9d to 6020126c10e8 (1 revision) (flutter/flutter#170862) 2025-06-19 engine-flutter-autoroll@skia.org Roll Skia from 291d41414fa7 to 1d8f7ebd23cc (2 revisions) (flutter/flutter#170857) 2025-06-19 engine-flutter-autoroll@skia.org Roll Dart SDK from b32559bca3cc to 4ab716b09e9d (9 revisions) (flutter/flutter#170855) 2025-06-19 jessy.yameogo@gmail.com remove --start-paused flag by default and set useDwdsWebSocketConnect… (flutter/flutter#170612) 2025-06-18 matanlurey@users.noreply.github.com Engine builders no longer require `is_fusion` (flutter/flutter#170849) 2025-06-18 engine-flutter-autoroll@skia.org Roll Skia from 5f110d5f48a3 to 291d41414fa7 (2 revisions) (flutter/flutter#170836) 2025-06-18 robert.ancell@canonical.com Use a shared vertex buffer for rendering layers. (flutter/flutter#170717) 2025-06-18 30870216+gaaclarke@users.noreply.github.com fixes deeplinking in uiscenedelegate migrated projects (flutter/flutter#170452) 2025-06-18 jonahwilliams@google.com [Impeller] fix array uniforms on GLES backend. (flutter/flutter#170710) 2025-06-18 chinmaygarde@google.com [Impeller] Update README to add section about custom embedders. (flutter/flutter#170077) 2025-06-18 jason-simmons@users.noreply.github.com Escape the forbidden strings in the regex used to check test command output (flutter/flutter#170702) 2025-06-18 30870216+gaaclarke@users.noreply.github.com License cpp jun16 (flutter/flutter#170716) 2025-06-18 chinmaygarde@google.com Work around newer compilers requiring the satisfaction of three-way comparison of EncodableValue. (flutter/flutter#170822) 2025-06-18 45459898+RamonFarizel@users.noreply.github.com Update didUnmountRenderObject text description (flutter/flutter#169628) 2025-06-18 engine-flutter-autoroll@skia.org Roll Skia from 297dbc32a6c7 to 5f110d5f48a3 (2 revisions) (flutter/flutter#170821) 2025-06-18 matanlurey@users.noreply.github.com Add an initial "Using feature flags" doc for the team. (flutter/flutter#170767) 2025-06-18 34465683+rkishan516@users.noreply.github.com Feat: Add mouse cursor for CupertinoDialogAction (flutter/flutter#169051) 2025-06-18 matanlurey@users.noreply.github.com Update `Engine-artifacts.md` to reflect flutter/cocoon/4785 (flutter/flutter#170751) 2025-06-18 alex.medinsh@gmail.com `CupertinoPicker` new onChanged behaviour (flutter/flutter#170202) 2025-06-18 pateltirth454@gmail.com Rename `entryPointBaseUrl` to `entrypointBaseUrl` (flutter/flutter#170166) 2025-06-18 engine-flutter-autoroll@skia.org Roll Skia from 1cb13a21b547 to 297dbc32a6c7 (4 revisions) (flutter/flutter#170809) 2025-06-18 engine-flutter-autoroll@skia.org Roll Packages from 25d4fa4 to 715a0a5 (2 revisions) (flutter/flutter#170808) 2025-06-18 engine-flutter-autoroll@skia.org Roll Skia from 0a106c038cd0 to 1cb13a21b547 (1 revision) (flutter/flutter#170801) 2025-06-18 derekx@google.com Add `--profile-microtasks` switch (flutter/flutter#170690) 2025-06-18 engine-flutter-autoroll@skia.org Roll Skia from ff7fffa5dac5 to 0a106c038cd0 (3 revisions) (flutter/flutter#170795) 2025-06-18 87239766+thakaredipali@users.noreply.github.com Add example for CupertinoExpansionTile transition modes (flutter/flutter#170335) 2025-06-18 stanleycocoa@gmail.com feat: Add radius to DividerThemeData. (flutter/flutter#169739) 2025-06-18 engine-flutter-autoroll@skia.org Roll Skia from 75af9450b121 to ff7fffa5dac5 (3 revisions) (flutter/flutter#170772) 2025-06-17 98614782+auto-submit[bot]@users.noreply.github.com Reverts "add run_gradle_lock_files_check.dart for new PR's that modify gradle files (#169245)" (flutter/flutter#170770) 2025-06-17 30870216+gaaclarke@users.noreply.github.com Started bridging the scene delegate to the lifecycle delegate for shortcuts (flutter/flutter#170180) 2025-06-17 jonahwilliams@google.com [ui] npot display_list allocation. (flutter/flutter#170447) 2025-06-17 kevmoo@users.noreply.github.com Prefer .of over .from (flutter/flutter#170750) 2025-06-17 47866232+chunhtai@users.noreply.github.com Fix RawGestureDetector semantics (flutter/flutter#170549) 2025-06-17 runar@socialscreen.no Use correct type for filterIdentifier (flutter/flutter#170343) 2025-06-17 matanlurey@users.noreply.github.com Remove and inline `license_header.txt` (flutter/flutter#170475) 2025-06-17 muhatashim@google.com add run_gradle_lock_files_check.dart for new PR's that modify gradle files (flutter/flutter#169245) 2025-06-17 engine-flutter-autoroll@skia.org Roll Dart SDK from 4fad61257b29 to b32559bca3cc (3 revisions) (flutter/flutter#170746) 2025-06-17 kevinjchisholm@google.com [release] Sync stable changelog to master (flutter/flutter#170691) 2025-06-17 engine-flutter-autoroll@skia.org Roll Packages from 03a6abb to 25d4fa4 (5 revisions) (flutter/flutter#170743) 2025-06-17 bkonyi@google.com [ Widget Preview ] Remove support for synthetic package:flutter_gen (flutter/flutter#170602) 2025-06-17 engine-flutter-autoroll@skia.org Roll Skia from 8879db3b3319 to 75af9450b121 (4 revisions) (flutter/flutter#170739) ...

…er/flutter#170767)

Add an initial 'Using feature flags' doc for the team.

b7df5ed

matanlurey requested review from bkonyi, jtmcdole and justinmc June 17, 2025 22:21

github-actions bot added c: contributor-productivity Team-specific productivity, code health, technical debt. framework flutter/packages/flutter repository. See also f: labels. d: docs/ flutter/flutter/docs, for contributors labels Jun 17, 2025

jtmcdole reviewed Jun 17, 2025

View reviewed changes

justinmc reviewed Jun 17, 2025

View reviewed changes

justinmc approved these changes Jun 17, 2025

View reviewed changes

Update doc to reflect PR feedback.

591254f

matanlurey added the autosubmit Merge PR when tree becomes green via auto submit App label Jun 18, 2025

auto-submit bot added this pull request to the merge queue Jun 18, 2025

Merged via the queue into flutter:master with commit ea010f3 Jun 18, 2025
8 checks passed

flutter-dashboard bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Jun 18, 2025

engine-flutter-autoroll mentioned this pull request Jun 19, 2025

Roll Flutter from 8303a96a0a99 to 44c6e065d777 (90 revisions) flutter/packages#9455

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jun 19, 2025

ea010f3 Add an initial "Using feature flags" doc for the team. (flutt…

b939aa1

…er/flutter#170767)

engine-flutter-autoroll mentioned this pull request Jun 19, 2025

Roll Flutter from 8303a96a0a99 to 2d383ad32e5d (91 revisions) flutter/packages#9456

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jun 19, 2025

ea010f3 Add an initial "Using feature flags" doc for the team. (flutt…

b80deac

…er/flutter#170767)

engine-flutter-autoroll mentioned this pull request Jun 19, 2025

Roll Flutter from 8303a96a0a99 to 85a9b4f38906 (93 revisions) flutter/packages#9457

Merged

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jun 19, 2025

ea010f3 Add an initial "Using feature flags" doc for the team. (flutt…

16ccfdc

…er/flutter#170767)

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 14, 2025

ea010f3 Add an initial "Using feature flags" doc for the team. (flutt…

6e05a55

…er/flutter#170767)

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 14, 2025

ea010f3 Add an initial "Using feature flags" doc for the team. (flutt…

07b9056

…er/flutter#170767)

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 15, 2025

ea010f3 Add an initial "Using feature flags" doc for the team. (flutt…

97aaf82

…er/flutter#170767)

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 15, 2025

ea010f3 Add an initial "Using feature flags" doc for the team. (flutt…

e598b25

…er/flutter#170767)

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 16, 2025

ea010f3 Add an initial "Using feature flags" doc for the team. (flutt…

2e59827

…er/flutter#170767)

		Feature flags allow conditionally, consistently, and covenentiantly change
		behavior.

		Additional parameters are required to make the flag configurable outside of
		a unit test.

		class WebDevices extends PollingDeviceDiscovery {
		WebDevices({required FeatureFlags featureFlags}) : _featureFlags = featureFlags;


		### Tool

		Feature flags can be accessed either by adding (and providing) an explicit

Add an initial "Using feature flags" doc for the team. #170767

Add an initial "Using feature flags" doc for the team. #170767

Uh oh!

Conversation

matanlurey commented Jun 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

justinmc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

justinmc left a comment

Choose a reason for hiding this comment

Uh oh!

matanlurey commented Jun 18, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

matanlurey commented Jun 17, 2025 •

edited

Loading