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

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, 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 use an __experimental prefix for any experimental interfaces. This is a signal to those reading our code that it should not be implemented in for production use. Currently this prefix is used in the following ways:

• Prefixing references that are experimental. An example would be PHP action or filter slugs.
• Prefixing functions or methods that are experimental.

Blocks behind flags

The majority of our feature flagging is blocks, this is a list of them:

Feature plugin flag

• Cart block (JS flag | PHP flag 1 | PHP flag 2).
• Checkout block (JS flag | PHP flag | PHP flag 2).

Experimental flag

• Single Product block (JS flag | PHP flag 1 | PHP flag 2 | webpack flag).
• ⚛️ Add to cart (JS flag).
• ⚛️ Product category list (JS flag).
• ⚛️ Product SKU (JS flag).
• ⚛️ Product stock indicator (JS flag).
• ⚛️ Product tag list (JS flag).

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).
• ⚛️ Product Price new controls (JS flag 1 | JS flag 2-1 | JS flag 2-2 | JS flag 2-3 | JS flag 2-4 | JS flag 2-5 | JS flag 2-6 | JS flag 2-7 | JS flag 2-8 | JS flag 2-9 | JS flag 3-1 | JS flag 3-2).
• ⚛️ Product Title new controls (JS flag 1 | JS flag 2-1 | JS flag 2-2 | JS flag 2-3 | JS flag 3-1 | JS flag 3-2 | JS flag 3-3).
• Utility function to pass styles to a block (JS flag).

Experimental plugin flag

• Inserting Product Element blocks globally from the inserter (JS flag).

Processes and commands that use a flag

• npm run build:deploy uses the feature plugin flag (env flag).
• travis uses the experimental flag when running tests (env flags).
• webpack creates a blocks.ini when running (env flag).
• webpack filters out experimental blocks when building. (env flag).
• certain e2e tests are skipped if the environment is not met (env flag).

Usages of __experimental prefix

• __experimental_woocommerce_blocks_checkout_update_order_meta hook when the draft order has been created or updated from the cart and is now ready for extensions to modify the metadata (experimental hook).
• __experimental_woocommerce_blocks_checkout_order_processed hook when order has completed processing and is ready for payment (experimental hook).
• __experimentalDeRegisterPaymentMethod function used to deregister a payment method, only used in tests (experimental function).
• __experimentalDeRegisterExpressPaymentMethod function used to deregister an express payment method, only used in tests (experimental function).
• __EXPERIMENTAL_TOTAL_LABEL_FILTER constant which maps to the wcBlocks.__experimental_total_label_filter hook name. Used to filter the Total label in the Cart and Checkout blocks (experimental constant).
• __experimental_woocommerce_blocks_hidden property in a Cart item data array that allows overwriting the hidden property. This is useful to make some cart item data visible/hidden depending if it needs to be displayed in Blocks or shortcode (experimental property).