From 6ec9548850a480638dd8019f5a876276be5b4354 Mon Sep 17 00:00:00 2001 From: Dmitriy Rabotyagov Date: Thu, 21 May 2026 14:59:26 +0200 Subject: [PATCH] [doc] Document usage of changelog At the moment project documentation does not contain any mention on how changelog should be produced. Some use reno, some use fragments. At the moment there is no transition from reno to antsibull format is available, so let's ask contributors to follow ansible's format of changelog fragments. In case we come up with a transition layer from reno to fragment format, or antsibull replacement, we can change documentation. Change-Id: I048f80af849d2872be866e44882d2a8fcbf01cfc Signed-off-by: Dmitriy Rabotyagov --- docs/contributing.md | 18 ++++++++++++++++++ docs/releasing.md | 13 ++++++------- docs/reviewing.md | 2 ++ 3 files changed, 26 insertions(+), 7 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 1b972f29..9e0cef67 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -80,6 +80,8 @@ openstacksdk], please read our [branching docs](branching.md). + be based on (be subclasses of) `OpenStackModule` in `ansible_collections.openstack.cloud.plugins.module_utils.openstack`, + should include `extends_documentation_fragment: openstack` in their `DOCUMENTATION` docstring, + + should contain `version_added` in their `DOCUMENTATION` docstring, where the version is + incremented minor version of the collection, + be registered in `meta/action_groups.yml` for enabling the variables to be set in [group level][ansible-module-defaults]. * Complex functionality, cloud interaction or interoperability code should be moved to [openstacksdk][openstacksdk]. @@ -136,6 +138,22 @@ openstacksdk], please read our [branching docs](branching.md). results with function parameter `filters`. openstacksdk's proxy layer does not provide an equivalent and thus the use of `search_users()` is perfectly fine. +## Changelog fragments + +Every patch that introduces a new feature, a bugfix, or a breaking change must include a changelog fragment. + +When you introduce a new module, the changelog fragment is not required. However, ensure that your module +`DOCUMENTATION` contains `version_added` field in it. Please, increment a minor version of the collection for +the value of `version_added`. For example, if current `openstack.cloud` collection version is `2.5.0`, you +need to use `version_added: 2.6.0`. + +As this is an Ansible collection, we follow the Ansible community standard for changelogs. Please note that **the `reno` +tool should not be used** in this repository. Instead, follow the guide linked below to create fragments manually in the +`changelogs/fragments/` directory. + +Please refer to the Ansible's [changelog fragments documentation](https://docs.ansible.com/projects/ansible/latest/community/development_process.html#creating-a-changelog-fragment) +for more details on the format, valid sections, and how to create a fragment. + ## Testing * Modules have to be tested with CI integration tests (if possible). diff --git a/docs/releasing.md b/docs/releasing.md index 8babb356..3d7571a5 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -2,16 +2,15 @@ ## Publishing to Ansible Galaxy -1. Create entry in [changelog.yaml](../changelogs/changelog.yaml) with commits since last release. - * Modules should be in a separate section `modules` - * Bugfixes and minor changes in their sections -2. Change version in [galaxy.yml](../galaxy.yml). Apply [Semantic Versioning](https://semver.org/): +1. Change version in galaxy.yml. Apply Semantic Versioning: * Increase major version for breaking changes or modules were removed * Increase minor version when modules were added * Increase patch version for bugfixes -3. Run `antsibull-changelog release` command (run `pip install antsibull` before) to generate [CHANGELOG.rst]( - ../CHANGELOG.rst) and verify correctness of generated files. -4. Commit changes to `changelog.yaml` and `galaxy.yml`, submit patch and wait until it has been merged +2. Run `antsibull-changelog release` command ([antsibull-changelog documentation]( + https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_changelogs.html)) + to aggregate changelog fragments into changelog.yaml and generate CHANGELOG.rst. +3. Verify correctness of generated files. +4. Commit changes to `changelog.yaml` and `galaxy.yml`, submit patch and wait until it has been merged. 5. Tag the release with version as it's described in [OpenStack docs]( https://docs.opendev.org/opendev/infra-manual/latest/drivers.html#tagging-a-release): * [Make sure you have a valid GnuPG key pair]( diff --git a/docs/reviewing.md b/docs/reviewing.md index 75ef25d4..ed629ba2 100644 --- a/docs/reviewing.md +++ b/docs/reviewing.md @@ -22,6 +22,8 @@ How to do a review? What to look for when reviewing patches? attributes to `name` to be consistent with other modules and with openstacksdk. When refactoring a module, then add the old attribute as an alias to keep backward compatibility. * Does the module have integration tests in `ci/roles`? +* Does the patch include a changelog fragment? Every new feature, or important bugfix must include one. Ensure that + the fragment follows the Ansible format and that `reno` is not used. * Is documentation in `DOCUMENTATION`, `RETURN` and `EXAMPLES` up to date? * Does `RETURN` list all values which are returned by the module? * Are descriptions, keys, names, types etc. in `RETURN` up to date and sorted?