fix: add experimental features maturity

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):

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.

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)