woocommerce/plugins/woocommerce-admin/docs/features/feature-flags.md

# Feature Flags

Features inside the `woocommerce-admin` repository can be in various states of completeness. In addition to the development copy of `woocommerce-admin`, feature plugin versions are bundled, and code is merged to WooCommerce core. To provide a way for improved control over how these features are released in these different environments, `woocommerce-admin` has a system for feature flags.

We currently support the following environments:

| Environment | Description                                                                                                                                                            |
|-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| development | Development - All features should be enabled in development. These flags are also used in both JS and PHP tests. Ran using `npm start`.                                |
| plugin      | Plugin - A packaged release of the featured plugin, for GitHub WordPress.org. Ran using `npm run-script build:release`. |                                    |
| core        | Core - assets/files ready and stable enough for core merge. Ran using `npm pack`. (@todo update this with publish command).


## Adding a new flag

Flags can be added to the files located in the `config/` directory. Make sure to add a flag for each environment and explicitly set the flag to false.
Please add new feature flags alphabetically so they are easy to find.

## Building custom plugin builds

Sometimes it is useful to create a test zip of a plugin, separate from the released WordPress.org version. This makes internal testing easier for non developers, removing the requirment of using Git and NPM commands. These releases are usually uploaded to GitHub releases as a pre release.

You can use the `build:release` command with the `--slug` and `--features` arguments to create a custom build. Base feature flags will be pulled from `config/plugin.json` and your additional changes are overlaid on top. When the build is complete, a `woocommerce-admin-$slug.zip` file will be generated.

For example, to create a `woocommerce-admin-onboarding.zip` build by enabling onboarding in addition to the feature flags defined in `config/plugin.json`, you would run:

`npm run build:release -- --slug onboarding --features '{"onboarding":true}'`.

## Basic Use - Client

The `window.wcAdminFeatures` constant is a global variable containing the feature flags.

Instances of `window.wcAdminFeatures` are replaced during the webpack build process by using webpack's [define plugin](https://webpack.js.org/plugins/define-plugin/). Using `webpack` for this allows us to eliminate dead code when making minified/production builds (`plugin`, or `core` environments).

To check if a feature is enabled, you can simplify check the boolean value of a feature:

```
{ window.wcAdminFeatures[ 'activity-panels' ] && <ActivityPanel /> }
```

We also expose CSS classes on the `body` tag, so that you can target specific feature states when they are enabled:

```
<body class="wp-admin woocommerce-page woocommerce-feature-enabled-activity-panels  ....">
```

## Basic Use - Server

Feature flags are also available via PHP. To ensure these are consistent with the built client assets, `includes/feature-flags.php` is generated by the plugin build process or `npm start`. Do not edit `includes/feature-flags.php` directly.

To check if a feature is enabled, you can use the `Automattic\WooCommerce\Admin\Loader::is_feature_enabled()`:

```
if ( \Automattic\WooCommerce\Admin\Loader::is_feature_enabled( 'activity-panels' ) ) {
	add_action( 'admin_header', 'wc_admin_activity_panel' );
}
```

If you name a directory after the flag in `includes/` with a `class-wc-admin-FEATURE.php` file, this code will also automatically be loaded.
Add Feature Flags (https://github.com/woocommerce/woocommerce-admin/pull/1500) * First pass at adding feature flags. Accessible over PHP and JS. * Hook up dev config to test enviornments, hook up features to their flags. * Cleanup some code and add documentation. Remove beta config. * Handle PR Feedback: Add devdocs flag, remove categories flag, fix auto-generated PHP warning. * Add todo for beta phase. * Handle PR feedback: Simplify is_array check, update build command, simplify test mock, remove empty webpack line. 2019-02-12 20:02:02 +00:00			`# Feature Flags`

Components: fix README url 2019-04-28 20:13:52 +00:00			Features inside the `woocommerce-admin` repository can be in various states of completeness. In addition to the development copy of `woocommerce-admin`, feature plugin versions are bundled, and code is merged to WooCommerce core. To provide a way for improved control over how these features are released in these different environments, `woocommerce-admin` has a system for feature flags.
Add Feature Flags (https://github.com/woocommerce/woocommerce-admin/pull/1500) * First pass at adding feature flags. Accessible over PHP and JS. * Hook up dev config to test enviornments, hook up features to their flags. * Cleanup some code and add documentation. Remove beta config. * Handle PR Feedback: Add devdocs flag, remove categories flag, fix auto-generated PHP warning. * Add todo for beta phase. * Handle PR feedback: Simplify is_array check, update build command, simplify test mock, remove empty webpack line. 2019-02-12 20:02:02 +00:00
			`We currently support the following environments:`

			`\| Environment \| Description \|`
			`\|-------------\|------------------------------------------------------------------------------------------------------------------------------------------------------------------------\|`
			\| development \| Development - All features should be enabled in development. These flags are also used in both JS and PHP tests. Ran using `npm start`. \|
			\| plugin \| Plugin - A packaged release of the featured plugin, for GitHub WordPress.org. Ran using `npm run-script build:release`. \| \|
WC_Admin_Loader/PHP Refactor + Method to publish core ready features (https://github.com/woocommerce/woocommerce-admin/pull/1863) * Try: Setup plugin to publish core library on npm * Documentation clean up. * Handle PR Feedback: Fix notices from happening in WC Core from API usage, fix sidebar dashboard ordering in menu, remove preload function check since we are supporting WP 5+, add a filter for preloading data and move usage to respective feature code, move features to a specific folder for bundiling, fix script translations. * Fix code comment on analytics preload * Continue refactoring code, and make it possible to launch 'embedded' features via the process as well. * Fix note hook * Fix note load order * Address PR feedback: Fix class name, load leaderboard endpoint * Remove example code prior to merge 2019-04-11 18:31:31 +00:00			\| core \| Core - assets/files ready and stable enough for core merge. Ran using `npm pack`. (@todo update this with publish command).
Add Feature Flags (https://github.com/woocommerce/woocommerce-admin/pull/1500) * First pass at adding feature flags. Accessible over PHP and JS. * Hook up dev config to test enviornments, hook up features to their flags. * Cleanup some code and add documentation. Remove beta config. * Handle PR Feedback: Add devdocs flag, remove categories flag, fix auto-generated PHP warning. * Add todo for beta phase. * Handle PR feedback: Simplify is_array check, update build command, simplify test mock, remove empty webpack line. 2019-02-12 20:02:02 +00:00

			`## Adding a new flag`

			Flags can be added to the files located in the `config/` directory. Make sure to add a flag for each environment and explicitly set the flag to false.
			`Please add new feature flags alphabetically so they are easy to find.`

Add the ability to create custom plugin builds (https://github.com/woocommerce/woocommerce-admin/pull/3044) * Add the ability to create custom plugin builds * Use $_ENV instead of $_SERVER inside the generate-feature-config CLI script. 2019-10-17 18:00:20 +00:00			`## Building custom plugin builds`

			`Sometimes it is useful to create a test zip of a plugin, separate from the released WordPress.org version. This makes internal testing easier for non developers, removing the requirment of using Git and NPM commands. These releases are usually uploaded to GitHub releases as a pre release.`

			You can use the `build:release` command with the `--slug` and `--features` arguments to create a custom build. Base feature flags will be pulled from `config/plugin.json` and your additional changes are overlaid on top. When the build is complete, a `woocommerce-admin-$slug.zip` file will be generated.

			For example, to create a `woocommerce-admin-onboarding.zip` build by enabling onboarding in addition to the feature flags defined in `config/plugin.json`, you would run:

			`npm run build:release -- --slug onboarding --features '{"onboarding":true}'`.

Add Feature Flags (https://github.com/woocommerce/woocommerce-admin/pull/1500) * First pass at adding feature flags. Accessible over PHP and JS. * Hook up dev config to test enviornments, hook up features to their flags. * Cleanup some code and add documentation. Remove beta config. * Handle PR Feedback: Add devdocs flag, remove categories flag, fix auto-generated PHP warning. * Add todo for beta phase. * Handle PR feedback: Simplify is_array check, update build command, simplify test mock, remove empty webpack line. 2019-02-12 20:02:02 +00:00			`## Basic Use - Client`

			The `window.wcAdminFeatures` constant is a global variable containing the feature flags.

			Instances of `window.wcAdminFeatures` are replaced during the webpack build process by using webpack's [define plugin](https://webpack.js.org/plugins/define-plugin/). Using `webpack` for this allows us to eliminate dead code when making minified/production builds (`plugin`, or `core` environments).

			`To check if a feature is enabled, you can simplify check the boolean value of a feature:`

			```
			`{ window.wcAdminFeatures[ 'activity-panels' ] && <ActivityPanel /> }`
			```

WC_Admin_Loader/PHP Refactor + Method to publish core ready features (https://github.com/woocommerce/woocommerce-admin/pull/1863) * Try: Setup plugin to publish core library on npm * Documentation clean up. * Handle PR Feedback: Fix notices from happening in WC Core from API usage, fix sidebar dashboard ordering in menu, remove preload function check since we are supporting WP 5+, add a filter for preloading data and move usage to respective feature code, move features to a specific folder for bundiling, fix script translations. * Fix code comment on analytics preload * Continue refactoring code, and make it possible to launch 'embedded' features via the process as well. * Fix note hook * Fix note load order * Address PR feedback: Fix class name, load leaderboard endpoint * Remove example code prior to merge 2019-04-11 18:31:31 +00:00			We also expose CSS classes on the `body` tag, so that you can target specific feature states when they are enabled:
Add Feature Flags (https://github.com/woocommerce/woocommerce-admin/pull/1500) * First pass at adding feature flags. Accessible over PHP and JS. * Hook up dev config to test enviornments, hook up features to their flags. * Cleanup some code and add documentation. Remove beta config. * Handle PR Feedback: Add devdocs flag, remove categories flag, fix auto-generated PHP warning. * Add todo for beta phase. * Handle PR feedback: Simplify is_array check, update build command, simplify test mock, remove empty webpack line. 2019-02-12 20:02:02 +00:00
			```
WC_Admin_Loader/PHP Refactor + Method to publish core ready features (https://github.com/woocommerce/woocommerce-admin/pull/1863) * Try: Setup plugin to publish core library on npm * Documentation clean up. * Handle PR Feedback: Fix notices from happening in WC Core from API usage, fix sidebar dashboard ordering in menu, remove preload function check since we are supporting WP 5+, add a filter for preloading data and move usage to respective feature code, move features to a specific folder for bundiling, fix script translations. * Fix code comment on analytics preload * Continue refactoring code, and make it possible to launch 'embedded' features via the process as well. * Fix note hook * Fix note load order * Address PR feedback: Fix class name, load leaderboard endpoint * Remove example code prior to merge 2019-04-11 18:31:31 +00:00			`<body class="wp-admin woocommerce-page woocommerce-feature-enabled-activity-panels ....">`
Add Feature Flags (https://github.com/woocommerce/woocommerce-admin/pull/1500) * First pass at adding feature flags. Accessible over PHP and JS. * Hook up dev config to test enviornments, hook up features to their flags. * Cleanup some code and add documentation. Remove beta config. * Handle PR Feedback: Add devdocs flag, remove categories flag, fix auto-generated PHP warning. * Add todo for beta phase. * Handle PR feedback: Simplify is_array check, update build command, simplify test mock, remove empty webpack line. 2019-02-12 20:02:02 +00:00			```

			`## Basic Use - Server`

			Feature flags are also available via PHP. To ensure these are consistent with the built client assets, `includes/feature-flags.php` is generated by the plugin build process or `npm start`. Do not edit `includes/feature-flags.php` directly.

Remove defunct filename prefix from remaining files. Excluding the note classes for third party compatibility. 2019-08-12 21:52:09 +00:00			To check if a feature is enabled, you can use the `Automattic\WooCommerce\Admin\Loader::is_feature_enabled()`:
Add Feature Flags (https://github.com/woocommerce/woocommerce-admin/pull/1500) * First pass at adding feature flags. Accessible over PHP and JS. * Hook up dev config to test enviornments, hook up features to their flags. * Cleanup some code and add documentation. Remove beta config. * Handle PR Feedback: Add devdocs flag, remove categories flag, fix auto-generated PHP warning. * Add todo for beta phase. * Handle PR feedback: Simplify is_array check, update build command, simplify test mock, remove empty webpack line. 2019-02-12 20:02:02 +00:00
			```
Remove defunct filename prefix from remaining files. Excluding the note classes for third party compatibility. 2019-08-12 21:52:09 +00:00			`if ( \Automattic\WooCommerce\Admin\Loader::is_feature_enabled( 'activity-panels' ) ) {`
Add Feature Flags (https://github.com/woocommerce/woocommerce-admin/pull/1500) * First pass at adding feature flags. Accessible over PHP and JS. * Hook up dev config to test enviornments, hook up features to their flags. * Cleanup some code and add documentation. Remove beta config. * Handle PR Feedback: Add devdocs flag, remove categories flag, fix auto-generated PHP warning. * Add todo for beta phase. * Handle PR feedback: Simplify is_array check, update build command, simplify test mock, remove empty webpack line. 2019-02-12 20:02:02 +00:00			`add_action( 'admin_header', 'wc_admin_activity_panel' );`
			`}`
WC_Admin_Loader/PHP Refactor + Method to publish core ready features (https://github.com/woocommerce/woocommerce-admin/pull/1863) * Try: Setup plugin to publish core library on npm * Documentation clean up. * Handle PR Feedback: Fix notices from happening in WC Core from API usage, fix sidebar dashboard ordering in menu, remove preload function check since we are supporting WP 5+, add a filter for preloading data and move usage to respective feature code, move features to a specific folder for bundiling, fix script translations. * Fix code comment on analytics preload * Continue refactoring code, and make it possible to launch 'embedded' features via the process as well. * Fix note hook * Fix note load order * Address PR feedback: Fix class name, load leaderboard endpoint * Remove example code prior to merge 2019-04-11 18:31:31 +00:00			```

Components: fix README url 2019-04-28 20:13:52 +00:00			If you name a directory after the flag in `includes/` with a `class-wc-admin-FEATURE.php` file, this code will also automatically be loaded.