Commit 2670f3cf570 for woocommerce

commit 2670f3cf57025745266b5c5a2c052201e6ba7d87
Author: Daniel Mallory <daniel.mallory@automattic.com>
Date:   Thu Jul 23 15:21:48 2026 +0100

    Mark the settings UI as experimental in the docs (#66938)

    docs(settings): Mark the settings UI as experimental

    The settings UI docs described the feature flag but never stated the
    stability of the API. Extension authors reading them could build
    against the PHP API, the schema format, or the JS package and expect
    them to hold between releases.

    Add an explicit experimental notice to the settings UI guide, the
    component registration guide, the WC_Settings_Page opt-in section, and
    the @woocommerce/settings-ui README, stating the surface can change in
    backwards-incompatible ways in any release.

    Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

diff --git a/docs/extensions/settings-and-config/extend-wc-settings-page.md b/docs/extensions/settings-and-config/extend-wc-settings-page.md
index fed8df1a205..5df7508f7af 100644
--- a/docs/extensions/settings-and-config/extend-wc-settings-page.md
+++ b/docs/extensions/settings-and-config/extend-wc-settings-page.md
@@ -344,6 +344,8 @@ For older WooCommerce versions, use the filter-based approach documented in [How

 ## Opt in to the React settings UI

+> **The settings UI is experimental** and subject to change. See the [settings UI status](./settings-ui.md#status) for details.
+
 `WC_Settings_Page` still owns registration, permissions, schema, and persistence when a page opts in to the React settings UI. To render a page with the React settings UI when the feature flag is enabled, return a settings UI adapter from `get_settings_ui_page()`.

 ```php
diff --git a/docs/extensions/settings-and-config/registering-settings-ui-components.md b/docs/extensions/settings-and-config/registering-settings-ui-components.md
index dfaf2abbc2a..907225ff651 100644
--- a/docs/extensions/settings-and-config/registering-settings-ui-components.md
+++ b/docs/extensions/settings-and-config/registering-settings-ui-components.md
@@ -6,6 +6,8 @@ sidebar_position: 8

 # Registering settings UI components

+> **The settings UI is experimental** and subject to change. See the [settings UI status](./settings-ui.md#status) for details.
+
 Use custom components when a WooCommerce settings field needs plugin-specific React UI that cannot be represented by a native field type.

 For most fields, prefer the native renderer. Custom components are best for specialized selectors, previews, or validation flows.
diff --git a/docs/extensions/settings-and-config/settings-ui.md b/docs/extensions/settings-and-config/settings-ui.md
index bbc9108003d..f3db6227396 100644
--- a/docs/extensions/settings-and-config/settings-ui.md
+++ b/docs/extensions/settings-and-config/settings-ui.md
@@ -6,12 +6,14 @@ sidebar_position: 7

 # Settings UI

-The settings UI is an opt-in path for rendering WooCommerce settings pages with React while keeping the existing `WC_Settings_Page` registration and save flow.
+The settings UI is an experimental, opt-in path for rendering WooCommerce settings pages with React while keeping the existing `WC_Settings_Page` registration and save flow.

 It is designed for extension authors who want to migrate incrementally. PHP still owns page registration, settings schema, permissions, script dependencies, and persistence. React owns field rendering and client-side interaction.

 ## Status

+> **The settings UI is experimental.** Until it is marked as stable, the PHP API under `Automattic\WooCommerce\Admin\Settings`, the schema format, and the `@woocommerce/settings-ui` package can change in backwards-incompatible ways in any release. Expect to update integrations between WooCommerce versions.
+
 -   The settings UI is behind the `settings-ui` feature flag.
 -   With the flag disabled, settings pages keep the legacy PHP renderer.
 -   With the flag enabled, a settings page still has to opt in explicitly.
diff --git a/packages/js/settings-ui/README.md b/packages/js/settings-ui/README.md
index 75834de54a2..6921e4923e5 100644
--- a/packages/js/settings-ui/README.md
+++ b/packages/js/settings-ui/README.md
@@ -2,6 +2,8 @@

 React utilities for WooCommerce settings pages that opt in to the settings UI renderer.

+> **This package is experimental.** Until it is marked as stable, its API and the settings UI schema can change in backwards-incompatible ways in any release.
+
 For the full integration guide, see [Settings UI](../../../docs/extensions/settings-and-config/settings-ui.md).

 ## Usage
diff --git a/packages/js/settings-ui/changelog/dev-mark-package-experimental b/packages/js/settings-ui/changelog/dev-mark-package-experimental
new file mode 100644
index 00000000000..2519c70a028
--- /dev/null
+++ b/packages/js/settings-ui/changelog/dev-mark-package-experimental
@@ -0,0 +1,4 @@
+Significance: patch
+Type: dev
+
+Mark the settings UI package as experimental in the README.