[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 <dmitriy.rabotyagov@cleura.com>

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.
+1. Change version in galaxy.yml. Apply Semantic Versioning:
-   * 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/):
    * 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](
+2. Run `antsibull-changelog release` command ([antsibull-changelog documentation](
-   ../CHANGELOG.rst) and verify correctness of generated files.
+   https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_changelogs.html))
-4. Commit changes to `changelog.yaml` and `galaxy.yml`, submit patch and wait until it has been merged
+   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?