Merge "[doc] Document usage of changelog"

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

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](

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?