Commit 042ce73ed7 for woocommerce
commit 042ce73ed7c3e7d5968f64b60fc67472481caa9e
Author: Néstor Soriano <konamiman@konamiman.com>
Date: Thu Feb 5 21:40:05 2026 +0100
Mention internal code in more places in the documentation (#63108)
* Mention internal code in more places in the documentation
Co-authored-by: botwoo <102544806+botwoo@users.noreply.github.com>
Co-authored-by: Brandon Kraft <public@brandonkraft.com>
diff --git a/docs/extensions/best-practices-extensions/extension-development-best-practices.md b/docs/extensions/best-practices-extensions/extension-development-best-practices.md
index f1fedb1cc8..c2e818b3ae 100644
--- a/docs/extensions/best-practices-extensions/extension-development-best-practices.md
+++ b/docs/extensions/best-practices-extensions/extension-development-best-practices.md
@@ -44,3 +44,4 @@ Merchants make use of WooCommerce extensions daily, and should have a unified an
20. **Log data that can be useful for debugging purposes**, with two conditions: Allow any logging as an 'opt in', and Use the [WC_Logger](https://woocommerce.com/wc-apidocs/class-WC_Logger.html) class. A user can then view logs on their system status page. Learn [how to add a link to logged data](/docs/code-snippets/link-to-logged-data) in your extension.
21. **Test Your Code with [WP_DEBUG](http://codex.wordpress.org/Debugging_in_WordPress)** mode on, so you can see all PHP warnings sent to the screen. This will flag things like making sure a variable is set before checking the value.
22. **Integrate the [Quality Insights Toolkit (QIT)](https://qit.woo.com/docs/) into your development workflow**: The QIT allows the ability to test your extensions against new releases of PHP, WooCommerce, and WordPress, as well as other active extensions, at the same time. Additionally, the toolkit includes a [command-line interface (CLI) tool](https://qit.woo.com/docs/installation-setup/cli-installation) that allows you to run and view tests against development builds. This helps to catch errors before releasing a new version.
+23. **Never use internal WooCommerce code in your extensions**. Classes in the `Automattic\WooCommerce\Internal` namespace and code marked with `@internal` annotations are for WooCommerce core use only. **Backwards compatibility is not guaranteed** for internal code: it may change, be renamed, or be removed in any future release. Using internal code in your extension may cause it to break when merchants update WooCommerce. See the [Internal namespace documentation](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/README.md) for details.
diff --git a/docs/extensions/core-concepts/README.md b/docs/extensions/core-concepts/README.md
index 881187ac83..db0aa07a89 100644
--- a/docs/extensions/core-concepts/README.md
+++ b/docs/extensions/core-concepts/README.md
@@ -8,6 +8,15 @@ Learn about everything from basic setup and architecture to advanced development
[Check if WooCommerce is active](./check-if-woo-is-active.md) to learn the proper way to ensure WooCommerce is installed and active before your code runs. This prevents errors and ensures your extension works reliably. You'll also want to understand the [core WooCommerce classes](./class-reference.md) and how to work with them, from the main `WooCommerce` class to `WC_Product`, `WC_Customer`, and `WC_Cart`.
+## Internal code boundaries
+
+WooCommerce contains both public APIs intended for extension use and internal infrastructure code. **Extensions must not use internal code**, as backwards compatibility between WooCommerce releases is not guaranteed:
+
+- **Internal namespace**: All classes under `Automattic\WooCommerce\Internal` are internal infrastructure.
+- **@internal annotations**: Code entities (classes, methods, hooks) marked with `@internal` in their docblocks.
+
+Using internal code may cause your extension to break when merchants update WooCommerce. See the [extension development best practices](../best-practices-extensions/extension-development-best-practices.md) and the [Internal namespace documentation](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/README.md) for details.
+
## Development patterns
[Adding actions and filters](./adding-actions-and-filters.md) to master the art of extending WooCommerce through hooks. Learn when and how to add actions and filters, following WordPress and WooCommerce standards. For long-term success, discover strategies for [writing maintainable code](./maintainability.md) and establishing update processes that keep your extensions current and secure. You'll also need to [manage deactivation and uninstallation](./handling-deactivation-and-uninstallation.md) to ensure your extension cleans up properly when deactivated or uninstalled, including scheduled actions, admin notes, and tasks.
diff --git a/docs/extensions/core-concepts/class-reference.md b/docs/extensions/core-concepts/class-reference.md
index f61ad60229..8044622c23 100644
--- a/docs/extensions/core-concepts/class-reference.md
+++ b/docs/extensions/core-concepts/class-reference.md
@@ -58,3 +58,14 @@ $cart_subtotal = $woocommerce->cart->get_cart_subtotal();
```
View the [WC_Cart Code Reference](https://woocommerce.github.io/code-reference/classes/WC-Cart.html) for a full list of methods contained in this class.
+
+## Internal Classes (Do Not Use)
+
+WooCommerce contains internal infrastructure code that's **not intended for use by extensions**:
+
+- **`Automattic\WooCommerce\Internal\*`**: All classes in this namespace are internal. Backwards compatibility is not guaranteed: these classes may change, be renamed, or be removed in future releases of WooCommerce.
+- **Classes with `@internal` annotations**: Equivalently, any class, method or hook marked with `@internal` in its docblock should not be used by extensions.
+
+Using internal code may cause your extension to break when WooCommerce is updated. Any code that's not internal per the above definition is public and generally safe to use.
+
+For more details, see the [Internal namespace documentation](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/README.md).
diff --git a/docs/extensions/getting-started-extensions/README.md b/docs/extensions/getting-started-extensions/README.md
index 68c6492be5..f67469a774 100644
--- a/docs/extensions/getting-started-extensions/README.md
+++ b/docs/extensions/getting-started-extensions/README.md
@@ -2,6 +2,10 @@
This section provides guides and resources for building, testing, and distributing WooCommerce extensions.
+## Important: Internal vs public code
+
+Not all WooCommerce code is intended for use by extensions. Classes in the `Automattic\WooCommerce\Internal` namespace and code marked with `@internal` are for WooCommerce core use only: backwards compatibility between WooCommerce releases is not guaranteed and your extension may break if you use them. See the [extension development best practices](../best-practices-extensions/extension-development-best-practices.md) and the [Internal namespace documentation](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/README.md).
+
## Getting started
- [Design a simple extension](/extensions/getting-started-extensions/how-to-design-a-simple-extension) - Learn extension architecture and best practices
diff --git a/plugins/woocommerce/README.md b/plugins/woocommerce/README.md
index 0d5baab55c..16a4930ad2 100644
--- a/plugins/woocommerce/README.md
+++ b/plugins/woocommerce/README.md
@@ -98,6 +98,10 @@ PHPStan configuration is stored in `phpstan.neon` at the root of the plugin dire
- [WooCommerce Code Reference](https://woocommerce.com/wc-apidocs/)
- [WooCommerce REST API Docs](https://woocommerce.github.io/woocommerce-rest-api-docs/)
+## A Note for Extension Developers
+
+If you're building a WooCommerce extension, be aware that not all code in this plugin is intended for external use. Classes in the `Automattic\WooCommerce\Internal` namespace and code marked with `@internal` annotations are internal infrastructure: backwards compatibility between WooCommerce releases is not guaranteed. See [src/Internal/README.md](src/Internal/README.md) for details.
+
## Reporting Security Issues
To disclose a security issue to our team, [please submit a report via HackerOne here](https://hackerone.com/automattic/).
diff --git a/plugins/woocommerce/changelog/pr-63108 b/plugins/woocommerce/changelog/pr-63108
new file mode 100644
index 0000000000..cee9e09e90
--- /dev/null
+++ b/plugins/woocommerce/changelog/pr-63108
@@ -0,0 +1,4 @@
+Significance: patch
+Type: dev
+
+Mention internal code in more places in the documentation