From 8d6a8583c9395d1be3af78c5cd4e4a0288e3cf62 Mon Sep 17 00:00:00 2001
From: Felix Fontein <felix@fontein.de>
Date: Thu, 3 Jun 2021 21:24:56 +0200
Subject: [PATCH] Improve and extend changelog logs (#74106) (#74753)

Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>
Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com>
(cherry picked from commit 4bf420706b2bf8591366e9eadf0db0afc6eccb17)
---
 .../rst/community/development_process.rst     | 68 ++++++++++++++++++-
 1 file changed, 67 insertions(+), 1 deletion(-)

diff --git a/docs/docsite/rst/community/development_process.rst b/docs/docsite/rst/community/development_process.rst
index e2e6fabedf0..9ca0044863f 100644
--- a/docs/docsite/rst/community/development_process.rst
+++ b/docs/docsite/rst/community/development_process.rst
@@ -142,7 +142,22 @@ We do not merge every PR. Here are some tips for making your PR useful, attracti
 Changelogs
 ----------
 
-Changelogs help users and developers keep up with changes to Ansible. Ansible builds a changelog for each release from fragments. You **must** add a changelog fragment to any PR that changes functionality or fixes a bug in ansible-core. You do not have to add a changelog fragment for PRs that add new modules and plugins, because our tooling does that for you automatically.
+Changelogs help users and developers keep up with changes to ansible-core and Ansible collections. Ansible and many collections build changelogs for each release from fragments. For ansible-core and collections using this model, you **must** add a changelog fragment to any PR that changes functionality or fixes a bug.
+
+You do not need a changelog fragment for PRs that:
+
+* add new modules and plugins, because Ansible tooling does that automatically;
+* contain only documentation changes.
+
+.. note::
+  Some collections require a changelog fragment for every pull request. They use the ``trivial:`` section for entries mentioned above that will be skipped when building a release changelog.
+
+
+More precisely:
+* Every bugfix PR must have a changelog fragment. The only exception are fixes to a change that has not yet been included in a release.
+* Every feature PR must have a changelog fragment.
+* New modules and plugins (except jinja2 filter and test plugins) must have ``versions_added`` set correctly, and do not need a changelog fragment. The tooling detects new modules and plugins by their ``versions_added`` value and announces them in the next release's changelog automatically.
+* New jinja2 filter and test plugins, and also new roles and playbooks (for collections) must have a changelog fragment. See :ref:`changelogs_how_to_format_j2_roles_playbooks` or the `antsibull-changelog documentation for such changelog fragments <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst#adding-new-roles-playbooks-test-and-filter-plugins>_` for information on how the fragments should look like.
 
 We build short summary changelogs for minor releases as well as for major releases. If you backport a bugfix, include a changelog fragment with the backport PR.
 
@@ -153,6 +168,8 @@ Creating a changelog fragment
 
 A basic changelog fragment is a ``.yaml`` file placed in the ``changelogs/fragments/`` directory.  Each file contains a yaml dict with keys like ``bugfixes`` or ``major_changes`` followed by a list of changelog entries of bugfixes or features.  Each changelog entry is rst embedded inside of the yaml file which means that certain constructs would need to be escaped so they can be interpreted by rst and not by yaml (or escaped for both yaml and rst if you prefer).  Each PR **must** use a new fragment file rather than adding to an existing one, so we can trace the change back to the PR that introduced it.
 
+PRs which add a new module or plugin do not necessarily need a changelog fragment. See the previous section :ref:`community_changelogs`. Also see the next section :ref:`changelogs_how_to_format` for the precise format changelog fragments should have.
+
 To create a changelog entry, create a new file with a unique name in the ``changelogs/fragments/`` directory of the corresponding repository. The file name should include the PR number and a description of the change. It must end with the file extension ``.yaml``. For example: ``40696-user-backup-shadow-file.yaml``
 
 A single changelog fragment may contain multiple sections but most will only contain one section. The toplevel keys (bugfixes, major_changes, and so on) are defined in the `config file <https://github.com/ansible/ansible/blob/devel/changelogs/config.yaml>`_ for our `release note tool <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst>`_. Here are the valid sections and a description of each:
@@ -185,6 +202,8 @@ Each changelog entry must contain a link to its issue between parentheses at the
 
 Most changelog entries are ``bugfixes`` or ``minor_changes``.
 
+.. _changelogs_how_to_format:
+
 Changelog fragment entry format
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -227,6 +246,53 @@ You can find more example changelog fragments in the `changelog directory <https
 
 After you have written the changelog fragment for your PR, commit the file and include it with the pull request.
 
+.. _changelogs_how_to_format_j2_roles_playbooks:
+
+Changelog fragment entry format for new jinja2 plugins, roles, and playbooks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+While new modules and plugins that are not jinja2 filter or test plugins are mentioned automatically in the generated changelog, jinja2 filter and test plugins, roles, and playbooks are not. To make sure they are mentioned, a changelog fragment in a specific format is needed:
+
+.. code-block:: yaml
+
+    # A new jinja2 filter plugin:
+    add plugin.filter:
+      - # The following needs to be the name of the filter itself, not of the file
+        # the filter is included in!
+        name: to_time_unit
+        # The description should be in the same format as short_description for
+        # other plugins and modules: it should start with an upper-case letter and
+        # not have a period at the end.
+        description: Converts a time expression to a given unit
+
+    # A new jinja2 test plugin:
+    add plugin.test:
+      - # The following needs to be the name of the test itself, not of the file
+        # the test is included in!
+        name: asn1time
+        # The description should be in the same format as short_description for
+        # other plugins and modules: it should start with an upper-case letter and
+        # not have a period at the end.
+        description: Check whether the given string is an ASN.1 time
+
+    # A new role:
+    add object.role:
+      - # This should be the short (non-FQCN) name of the role.
+        name: nginx
+        # The description should be in the same format as short_description for
+        # plugins and modules: it should start with an upper-case letter and
+        # not have a period at the end.
+        description: A nginx installation role
+
+    # A new playbook:
+    add object.playbook:
+      - # This should be the short (non-FQCN) name of the playbook.
+        name: wipe_server
+        # The description should be in the same format as short_description for
+        # plugins and modules: it should start with an upper-case letter and
+        # not have a period at the end.
+        description: Wipes a server
+
 .. _backport_process:
 
 Backporting merged PRs in ``ansible-core``