diff --git a/README.md b/README.md index 2196a6e..6c691f8 100644 --- a/README.md +++ b/README.md @@ -75,3 +75,33 @@ ansible-test integration --color --local -vvv hetzner.hcloud.server // Executed ## Releasing a new version If there are releasable changes, `release-please` will open a PR on GitHub with the proposed version. When this PR is merged, `release-please` will tag the release. + +## Releasing experimental features + +To publish experimental features as part of regular releases: + +- an announcement, including a link to a changelog entry, must be added to the release notes. + +- an `Experimental` notice, including a link to a changelog entry, must be added to the experimental plugins documentation: + + ```py + DOCUMENTATION = """ + --- + module: product + + 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. + """ + ``` + +- 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") + + class AnsibleProduct(AnsibleHCloud): + def __init__(self, module: AnsibleModule): + product_experimental_warning(module) + super().__init__(module) + ``` diff --git a/plugins/module_utils/experimental.py b/plugins/module_utils/experimental.py new file mode 100644 index 0000000..3ac0bbc --- /dev/null +++ b/plugins/module_utils/experimental.py @@ -0,0 +1,31 @@ +# Copyright: (c) 2025, Hetzner Cloud GmbH + +from __future__ import annotations + +from .hcloud import AnsibleModule + + +def experimental_warning_function(product: str, url: str): + """ + Create a reusable experimental warning function. + + Usage: + + product_experimental_warning = experimental_warning_function( + "Product", "https://docs.hetzner.cloud/changelog#new-product" + ) + + class AnsibleProduct(AnsibleHCloud): + def __init__(self, module: AnsibleModule): + product_experimental_warning(module) + super().__init__(module) + + :param product: Name of the experimental product. + :param url: Changelog URL announcing the experimental product. + """ + message = f"Experimental: {product} is experimental, breaking changes may occur within minor releases. See {url} for more details." + + def fn(module: AnsibleModule): + module.warn(message) + + return fn