From 1251ee0e6f2f0b16cc598b328cd4f4662bef6476 Mon Sep 17 00:00:00 2001
From: "Jonas L." <jooola@users.noreply.github.com>
Date: Mon, 29 Sep 2025 18:10:07 +0200
Subject: [PATCH] fix: add experimental features maturity (#698)

##### SUMMARY

Allow to specify the maturity of the experimental product.

##### ISSUE TYPE

- Bugfix Pull Request
---
 README.md                            |  8 ++++++--
 docs/docsite/rst/guides.rst          | 19 +++++++++++++++++++
 plugins/module_utils/experimental.py | 13 ++++++++-----
 3 files changed, 33 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 6c691f8..a3b3125 100644
--- a/README.md
+++ b/README.md
@@ -91,14 +91,18 @@ To publish experimental features as part of regular releases:
 
   description:
       - Create, update and manage Product on the Hetzner Cloud.
-      - B(Experimental:) Product is experimental, breaking changes may occur within minor releases. See https://docs.hetzner.cloud/changelog#new-product for more details.
+      - B(Experimental:) $PRODUCT is $MATURITY, breaking changes may occur within minor releases. See https://docs.hetzner.cloud/changelog#$SLUG for more details.
   """
   ```
 
 - a `Experimental` warning, including a link to a changelog entry, must be logged when experimental plugins are being used:
 
   ```py
-  product_experimental_warning = experimental_warning_function("Product", "https://docs.hetzner.cloud/changelog#new-product")
+  product_experimental_warning = experimental_warning_function(
+      "$PRODUCT",
+      "$MATURITY",
+      "https://docs.hetzner.cloud/changelog#$SLUG",
+  )
 
   class AnsibleProduct(AnsibleHCloud):
       def __init__(self, module: AnsibleModule):
diff --git a/docs/docsite/rst/guides.rst b/docs/docsite/rst/guides.rst
index eccf268..79ae2a4 100644
--- a/docs/docsite/rst/guides.rst
+++ b/docs/docsite/rst/guides.rst
@@ -48,3 +48,22 @@ example if you want to store your API token in a vault:
             server_type: cx22
             image: debian-12
             state: present
+
+Experimental features
+=====================
+
+Experimental features are published as part of our regular releases (e.g. a product
+public beta). During an experimental phase, breaking changes on those features may occur
+within minor releases.
+
+The stability of experimental features is not related to the stability of its upstream API.
+
+Experimental features have different levels of maturity (e.g. experimental, alpha, beta)
+based on the maturity of the upstream API.
+
+While experimental features will be announced in the release notes, you can also find
+whether a module, or filter is experimental in its documentation:
+
+.. code-block:: txt
+
+    Experimental: $PRODUCT is $MATURITY, breaking changes may occur within minor releases. See https://docs.hetzner.cloud/changelog#$SLUG for more details.
diff --git a/plugins/module_utils/experimental.py b/plugins/module_utils/experimental.py
index 3ac0bbc..e253e87 100644
--- a/plugins/module_utils/experimental.py
+++ b/plugins/module_utils/experimental.py
@@ -5,14 +5,16 @@ from __future__ import annotations
 from .hcloud import AnsibleModule
 
 
-def experimental_warning_function(product: str, url: str):
+def experimental_warning_function(product: str, maturity: str, url: str):
     """
     Create a reusable experimental warning function.
 
     Usage:
 
         product_experimental_warning = experimental_warning_function(
-            "Product", "https://docs.hetzner.cloud/changelog#new-product"
+            "Product",
+            "in beta",
+            "https://docs.hetzner.cloud/changelog#new-product",
         )
 
         class AnsibleProduct(AnsibleHCloud):
@@ -20,10 +22,11 @@ def experimental_warning_function(product: str, url: str):
                 product_experimental_warning(module)
                 super().__init__(module)
 
-    :param product: Name of the experimental product.
-    :param url: Changelog URL announcing the experimental product.
+    :param product: Name of the product.
+    :param maturity: Maturity of the product.
+    :param url: Changelog URL announcing the product.
     """
-    message = f"Experimental: {product} is experimental, breaking changes may occur within minor releases. See {url} for more details."
+    message = f"Experimental: {product} is {maturity}, breaking changes may occur within minor releases. See {url} for more details."
 
     def fn(module: AnsibleModule):
         module.warn(message)