60 lines
3.8 KiB
Markdown
60 lines
3.8 KiB
Markdown
# 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.
|