Add new doc referencing feature flags and experimental interfaces.

.github/pull_request_template.md

@@ -4,6 +4,7 @@
 Fixes #
 
 <!-- Don't forget to update the title with something descriptive. -->
+<!-- If your pull request implements a feature flag, make sure you update [this doc](../docs/blocks/features-and-blocks-behind-a-flag.md) -->
 
 #### Accessibility
 
@@ -13,6 +14,7 @@ Fixes #
 - [ ] I've tested using a screen reader
 - [ ] All animations respect [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion)
 - [ ] All text has [at least a 4.5 color contrast with its background](https://webaim.org/resources/contrastchecker/)
+- [ ] I've updated [this doc](../docs/blocks/feature-flags-and-experimental-interfaces.md) for any feature flags or experimental interfaces implemented in this pull request.
 
 ### Screenshots
 

docs/blocks/README.md

@@ -4,4 +4,5 @@ This folder contains documentation for specific Blocks and Blocks functionality.
 
 | Document                                                  | Description                                            |
 | --------------------------------------------------------- | ------------------------------------------------------ |
-| [Stock Reservation during Checkout](stock-reservation.md) | This doc covers the Checkout Stock Reservation system. |  |
+| [Stock Reservation during Checkout](stock-reservation.md) | This doc covers the Checkout Stock Reservation system. |
+| [Features Flags and Experimental interfaces](./feature-flags-and-experimental-interfaces.md) | This doc outlines all the current features that are gated behind a feature or experimental flag as well as any interfaces that are experimental |

docs/blocks/feature-flags-and-experimental-interfaces.md

@@ -0,0 +1,53 @@
+We have feature gating system setup in our plugin that defines what is accessible to the public and what is not, it has three phases:
+
+*   **Core flag `WOOCOMMERCE_BLOCKS_PHASE=1`:** anything that is not hidden behind a flag, falls under this category, and it contains all of the code that runs on WooCommerce Core plugin.
+*   **Feature plugin flag** `**WOOCOMMERCE_BLOCKS_PHASE=**2`**:** anything that is behind this flag is code that is shipped to our [feature plugin](https://wordpress.org/plugins/woo-gutenberg-products-block/), the files of blocks behind this flag are also present in WooCommerce Core, just not active.
+*   **Experimental flag** `**WOOCOMMERCE_BLOCKS_PHASE**=3`: This flag contains things that we're not shipping yet, so unfinished work mostly. These features are only available in developer builds of the plugin.
+
+We also utilize the following for indicating interfaces that are experimental and thus should not be used in production builds:
+
+- `__experimental` prefix is used in any PHP actions or filter slugs and also for any JS functions.
+
+## Blocks behind flags
+
+The majority of our feature flagging is blocks, this is a list of them:
+
+### Feature plugin flag
+
+*   Cart block ([JS flag](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/9b76ea7a1680e68cc20bfee01078e43ccfc996bd/assets/js/blocks/cart-checkout/cart/index.js#L53) | [PHP flag 1](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/e167b2c99c68e8113b4e371fefdd6f9a356ed2e8/src/Library.php#L74-L77) | [PHP flag 2](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/src/Assets.php#L92-L95)).
+*   Checkout block ([JS flag](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/9b76ea7a1680e68cc20bfee01078e43ccfc996bd/assets/js/blocks/cart-checkout/checkout/index.js#L52) | [PHP flag](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/e167b2c99c68e8113b4e371fefdd6f9a356ed2e8/src/Library.php#L74-L77) | [PHP flag 2](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/src/Assets.php#L92-L95)).
+
+### Experimental flag
+
+*   Single Product block ([JS flag](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/9b76ea7a1680e68cc20bfee01078e43ccfc996bd/assets/js/blocks/single-product/index.js#L43) | [PHP flag 1](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/e167b2c99c68e8113b4e371fefdd6f9a356ed2e8/src/Library.php#L79-L81) | [PHP flag 2](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/src/Assets.php#L88-L90) | [webpack flag](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/bin/webpack-entries.js#L48-L50)).
+*   ⚛️ Add to cart ([JS flag](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/add-to-cart/index.js#L29-L32)).
+*   ⚛️ Product category list ([JS flag](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/category-list/index.js#L29-L32)).
+*   ⚛️ Product SKU ([JS flag](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/sku/index.js#L29-L33)).
+*   ⚛️ Product stock indicator ([JS flag](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/stock-indicator/index.js#L29-L33)).
+*   ⚛️ Product tag list ([JS flag](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/tag-list/index.js#L29-L33)).
+
+## Features behind flags
+
+We also have individual features or code blocks behind a feature flag, this is a list of them:
+
+### Feature plugin flag
+
+*   draft order and cleanup process ([PHP flag](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/e167b2c99c68e8113b4e371fefdd6f9a356ed2e8/src/Domain/Services/DraftOrders.php#L42-L51)).
+*   ⚛️ Product Price new controls ([JS flag 1](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/price/attributes.js#L13-L44) | [JS flag 2-1](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/price/block.js#L109-L110) | [JS flag 2-2](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/price/block.js#L161-L162) | [JS flag 2-3](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/price/block.js#L165) | [JS flag 2-4](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/price/block.js#L196-L197) | [JS flag 2-5](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/price/block.js#L199) | [JS flag 2-6](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/price/block.js#L210-L211) | [JS flag 2-7](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/price/block.js#L213) | [JS flag 2-8](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/price/block.js#L231) | [JS flag 2-9](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/price/block.js#L233) | [JS flag 3-1](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/price/edit.js#L59-L108) | [JS flag 3-2](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/price/edit.js#L114-L131)).
+*   ⚛️ Product Title new controls ([JS flag 1](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/title/attributes.js#L21-L40) | [JS flag 2-1](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/title/block.js#L70-L72) | [JS flag 2-2](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/title/block.js#L94-L95) | [JS flag 2-3](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/title/block.js#L104) | [JS flag 3-1](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/title/edit.js#L47-L54) | [JS flag 3-2](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/title/edit.js#L77-L107) | [JS flag 3-3](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/title/edit.js#L116-L129)).
+*   Utility function to pass styles to a block ([JS flag](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/9ebddbc5d21eb3cc67fedddbccbd86453313eb64/assets/js/atomic/utils/block-styling.js#L6-L12)).
+
+### Experimental plugin flag
+
+*   Inserting Product Element blocks globally from the inserter ([JS flag](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/assets/js/atomic/blocks/product-elements/shared/config.js#L25-L27)).
+*   Support for signup / create account during checkout ([see PR for details](https://github.com/woocommerce/woocommerce-gutenberg-products-block/pull/2851)).
+
+## Processes and commands that uses a flag
+
+*   `npm run build:deploy` uses the feature plugin flag ([env flag](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/c0de18ec0a798c072420c67a689e4cc4d3ac77c9/package.json#L28)).
+*   travis uses the experimental flag when running tests ([env flags](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/d6a506c19056d42d40743ae0126153fb81004672/.travis.yml#L68-L143)).
+*   webpack creates a `blocks.ini` when running ([env flag](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/bin/webpack-configs.js#L95-L102)).
+*   webpack filters out experimental blocks when building. ([env flag](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/bin/webpack-entries.js#L61-L66)).
+*   certain e2e tests are skipped if the environment is not met ([env flag](https://github.com/woocommerce/woocommerce-gutenberg-products-block//blob/50e7411aee51afb3fbfa8561e297085ee44e40c0/tests/e2e-tests/specs/backend/cart.test.js#L18)).
+
+## Usages of `__experimental` prefix