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?