Document how to release a collection (#77391)

Co-authored-by: Divine Odazie <dodazie@gmail.com>

docs/docsite/rst/community/collection_contributors/collection_integration_about.rst

@@ -107,18 +107,18 @@ Covering modules / new features
 
 When covering a module, cover all its options separately and their meaningful combinations. Every possible use of the module should be tested against:
 
-- Idempotency (Does rerunning a task report no changes?)
+- Idempotency - Does rerunning a task report no changes?
-- Check-mode (Does dry-running a task behave the same as a real run? Does it not make any changes?)
+- Check-mode - Does dry-running a task behave the same as a real run? Does it not make any changes?
-- Return values (Does the module return values consistently under different conditions?)
+- Return values - Does the module return values consistently under different conditions?
 
 Each test action has to be tested at least the following times:
 
-- Perform an action in check-mode if supported (this should indicate a change).
+- Perform an action in check-mode if supported. This should indicate a change.
 - Check with another module that the changes have ``not`` been actually made.
-- Perform the action for real (this should indicate a change).
+- Perform the action for real. This should indicate a change.
 - Check with another module that the changes have been actually made.
-- Perform the action again in check-mode (this should indicate ``no`` change).
+- Perform the action again in check-mode. This should indicate ``no`` change.
-- Perform the action again for real (this should indicate ``no`` change).
+- Perform the action again for real. This should indicate ``no`` change.
 
 To check a task:
 
@@ -128,7 +128,7 @@ To check a task:
   #. Expected return values.
 
 2. If the module changes the system state, check the actual system state using at least one other module. For example, if the module changes a file, we can check that the file has been changed by checking its checksum with the :ref:`stat <ansible_collections.ansible.builtin.stat_module>` module before and after the test tasks.
-3. Run the same task with ``check_mode: yes`` (if check-mode is supported by the module). Check with other modules that the actual system state has not been changed.
+3. Run the same task with ``check_mode: yes`` if check-mode is supported by the module. Check with other modules that the actual system state has not been changed.
 4. Cover cases when the module must fail. Use the ``ignore_errors: yes`` option and check the returned message with the ``assert`` module.
 
 Example:

docs/docsite/rst/community/collection_contributors/collection_integration_add.rst

@@ -229,7 +229,7 @@ That is enough for our very basic example.
 
 In the first task, we run the ``postgresql_info`` module to fetch information from the database we installed and launched with the ``setup_postgresql_db`` target. We are saving the values returned by the module into the ``result`` variable.
 
-In the second task, we check the ``result`` variable (what the first task returned) with the ``assert`` module. We expect that, among other things, the result has the version and reports that the system state has not been changed.
+In the second task, we check the ``result`` variable, which is what the first task returned, with the ``assert`` module. We expect that, among other things, the result has the version and reports that the system state has not been changed.
 
 13. Run the tests in the Ubuntu 20.04 docker container:
 

docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst

@@ -0,0 +1,319 @@
+.. _collection_release_with_branches:
+
+Releasing collections with release branches
+============================================
+
+Collections MUST follow the `semantic versioning <https://semver.org/>`_ rules. See :ref:`releasing_collections` for high-level details.
+
+.. contents::
+  :local:
+
+
+Release planning and announcement
+----------------------------------
+
+#. Announce your intention to release the collection in a corresponding pinned release issue/community pinboard of the collection and in the ``#ansible-community`` `Matrix/IRC channel <https://docs.ansible.com/ansible/devel/community/communication.html#real-time-chat>`_. Repeat the announcement in any other dedicated channels if they exist.
+
+#. Ensure all the other repository maintainers are informed about the time of the following release.
+
+
+Releasing major collection versions
+-------------------------------------
+
+The new version is assumed to be ``X.0.0``.
+
+1. If you are going to release the ``community.general`` and ``community.network`` collections, create new ``backport-X`` and ``needs_backport_to_stable_X`` labels in the corresponding repositories. Copy the styles and descriptions from the corresponding existing labels.
+
+2. Ensure you are in a default branch in your local fork. These examples use ``main``.
+
+  .. code-block:: bash
+
+    git status
+    git checkout main     # if needed
+
+
+3. Update your local fork:
+
+  .. code-block:: bash
+
+    git pull --rebase upstream main
+
+
+Creating the release branch
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Create a branch ``stable-X``. Replace ``X`` with a correct number and push it to the **upstream** repository, NOT to the ``origin``.:
+
+  .. code-block:: bash
+
+    git branch stable-X main
+    git push upstream stable-X
+
+
+2. Create and checkout to another branch from the ``main`` branch:
+
+  .. code-block:: bash
+
+    git checkout -b update_repo
+
+
+3. Update the version in ``galaxy.yml`` in the branch to the next **expected** version, for example, ``X.1.0``.
+
+
+Creating the changelogs
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Replace ``changelogs/changelog.yml`` with:
+
+  .. code-block:: yaml
+
+    ancestor: X.0.0
+    releases: {}
+
+
+2. Remove all changelog fragments from ``changelogs/fragments/``. Removing the changelog fragments ensures that every major release has a changelog describing changes since the last major release.
+
+3. Add and commit all the changes made. Push the branch to the ``origin`` repository.
+
+4. Create a pull request in the collection repository. If CI tests pass, merge the pull request since the ``main`` branch is expecting changes for the next minor/major versions
+
+5. Switch to the ``stable-X`` branch.
+
+6. In the ``stable-X`` branch, ensure that ``galaxy.yml`` contains the correct version number ``X.0.0``. If not, update it.
+
+7. In the ``stable-X`` branch, add a changelog fragment ``changelogs/fragments/X.0.0.yml`` with the content:
+
+  .. code-block:: yaml
+
+    release_summary: |-
+      Write some text here that should appear as the release summary for this version.
+      The format is reStructuredText, but not a list as for regular changelog fragments.
+      This text will be inserted into the changelog.
+
+  For example:
+
+  .. code-block:: yaml
+
+    release_summary: This is release 2.0.0 of ``community.foo``, released on YYYY-MM-DD.
+
+
+8. In the ``stable-X`` branch, generate the changelogs:
+
+  .. code-block:: bash
+
+    antsibull-changelog release --cummulative-release
+
+
+9. In the ``stable-X`` branch, verify that the ``CHANGELOG.rst`` looks as expected.
+
+10. In the ``stable-X`` branch, update ``README.md`` so that the changelog link points to ``/tree/stable-X/`` and no longer to ``/tree/main/``, and change badges respectively, for example, in case of AZP, add ``?branchName=stable-X`` to the AZP CI badge (https://dev.azure.com/ansible/community.xxx/_apis/build/status/CI?branchName=stable-X).
+
+11. In the ``stable-X`` branch, add, commit, and push changes to ``README.md``, ``CHANGELOG.rst`` and ``changelogs/changelog.yaml``, and potentially deleted/archived fragments to the **upstream** repository, NOT to the ``origin``.
+
+
+Publishing the collection
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. In the ``stable-X`` branch, add an annotated tag to the last commit with the collection version ``X.0.0``. Pushing this tag to the ``upstream`` repository will make Zuul publish the collection on `Ansible Galaxy <https://galaxy.ansible.com/>`_.
+
+  .. code-block:: bash
+
+    git tag -n    # see current tags and their comments
+    git tag -a NEW_VERSION -m "comment here"    # the comment can be, for example, "community.foo: 2.0.0"
+    git push upstream NEW_VERSION
+
+
+2. Wait until the new version is published on the collection's `Ansible Galaxy <https://galaxy.ansible.com/>`_ page. It will appear in a list of tarballs available to download.
+
+3. Add a GitHub release for the new tag. The title should be the version and content, such as -  ``See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes``.
+
+
+4. Announce the release through the `Bullhorn Newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_.
+
+5. Announce the release in the pinned release issue/community pinboard of the collection and in the ``#ansible-community`` `Matrix/Libera.Chat IRC channel <https://docs.ansible.com/ansible/devel/community/communication.html#real-time-chat>`_.
+
+6. In the ``stable-X`` branch, update the version in ``galaxy.yml`` to the next **expected** version, for example, ``X.1.0``. Add, commit and push to the **upstream** repository.
+
+
+Releasing minor collection versions
+-------------------------------------
+
+The new version is assumed to be ``X.Y.0``. All changes that should go into it are expected to be previously backported from the default branch to the ``stable-X`` branch.
+
+Creating the changelogs
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. In the ``stable-X`` branch, make sure that ``galaxy.yml`` contains the correct version number ``X.Y.0``. If not, update it.
+
+2. In the ``stable-X`` branch, add a changelog fragment ``changelogs/fragments/X.Y.0.yml`` with content:
+
+  .. code-block:: yaml
+
+    release_summary: |-
+      Write some text here that should appear as the release summary for this version.
+      The format is reStructuredText, but not a list as for regular changelog fragments.
+      This text will be inserted into the changelog.
+
+
+3. In the ``stable-X`` branch, run:
+
+  .. code-block:: bash
+
+   antsibull-changelog release
+
+
+4. In the ``stable-X`` branch, verify that ``CHANGELOG.rst`` looks as expected.
+
+5. In the ``stable-X`` branch, add, commit, and push changes to ``CHANGELOG.rst`` and ``changelogs/changelog.yaml``, and potentially deleted/archived fragments to the **upstream** repository, NOT to the origin.
+
+
+Publishing the collection
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. In the ``stable-X`` branch, add an annotated tag to the last commit with the collection version ``X.Y.0``. Pushing this tag to the ``upstream`` repository will make Zuul publish the collection on `Ansible Galaxy <https://galaxy.ansible.com/>`_.
+
+  .. code-block:: bash
+
+   git tag -n    # see current tags and their comments
+   git tag -a NEW_VERSION -m "comment here"    # the comment can be, for example, "community.foo: 2.1.0"
+   git push upstream NEW_VERSION
+
+
+2. Wait until the new version is published on the collection's `Ansible Galaxy <https://galaxy.ansible.com/>`_ page. The published version will appear in a list of tarballs available to download.
+
+3. Add a GitHub release for the new tag. The title should be the version and content, such as -  ``See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes``.
+
+4. Announce the release through the `Bullhorn Newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_.
+
+5. Announce the release in the pinned release issue/community pinboard of the collection and in the ``#ansible-community`` `Matrix/IRC channel <https://docs.ansible.com/ansible/devel/community/communication.html#real-time-chat>`_. Additionally, you can announce it using GitHub's Releases system.
+
+6. In the ``stable-X`` branch, update the version in ``galaxy.yml`` to the next **expected** version, for example, if you have released ``X.1.0``, the next expected version could be ``X.2.0``. Add, commit and push to the **upstream** repository.
+
+7. Checkout to the ``main`` branch.
+
+8. In the ``main`` branch:
+
+  #. If more minor versions are released before the next major version, update the version in ``galaxy.yml`` to ``X.(Y+1).0`` as well. Create a dedicated pull request and merge.
+
+  #. If the next version will be a new major version, create a pull request where you update the version in ``galaxy.yml`` to ``(X+1).0.0``. Note that the sanity tests will most likely fail since there will be deprecations with removal scheduled for ``(X+1).0.0``, which are flagged by the tests.
+
+  For every such deprecation, decide:
+  
+  * Whether to remove them now. For example you remove the complete ``modules/plugins`` or you remove redirects. 
+  * Whether to add ignore entries to the corresponding ``tests/sanity/ignore-*.txt`` file and create issues, for example for removed features in ``modules/plugins``.
+
+  Once the CI tests pass, merge the pull request. Make sure that this pull request is merged not too much later after the release
+  for ``verison_added`` sanity tests not to expect the wrong version for the new feature pull request.
+
+.. note::
+
+  It makes sense to already do some removals in the days before the release. These removals must happen in the main branch and must not be backported.
+
+
+Releasing patch versions
+-------------------------
+
+The new version is assumed to be ``X.Y.Z``, and the previous patch version is assumed to be ``X.Y.z`` with ``z < Z``.  ``z`` is frequently``0`` snce patch releases are uncommon.
+
+Releasing when more minor versions are expected
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Checkout the ``X.Y.z`` tag.
+
+2. Update ``galaxy.yml`` so that the version is ``X.Y.Z``. Add and commit.
+
+3. Cherry-pick all changes from ``stable-X`` that were added after ``X.Y.z`` and should go into ``X.Y.Z``.
+
+4. Add a changelog fragment ``changelogs/fragments/X.Y.Z.yml`` with content:
+
+  .. code-block:: yaml
+
+    release_summary: |-
+      Write some text here that should appear as the release summary for this version.
+      The format is reStructuredText but not a list as for regular changelog fragments.
+      This text will be inserted into the changelog.
+
+  Add to git and commit.
+
+5. Generate the changelogs.
+
+.. code-block:: bash
+
+   antsibull-changelog release
+
+6. Verify that ``CHANGELOG.rst`` looks as expected.
+
+7. Add and commit changes to ``CHANGELOG.rst`` and ``changelogs/changelog.yaml``, and potentially deleted/archived fragments.
+
+**Publishing the collection**
+
+
+1. Add an annotated tag to the last commit with the collection version ``X.Y.Z``. Pushing this tag to the ``upstream`` repository will make Zuul publish the collection on `Ansible Galaxy <https://galaxy.ansible.com/>`_.
+
+  .. code-block:: bash
+
+   git tag -n    # see current tags and their comments
+   git tag -a NEW_VERSION -m "comment here"    # the comment can be, for example, "community.foo: 2.1.1"
+   git push upstream NEW_VERSION
+
+
+2. Wait until the new version is published on the collection's `Ansible Galaxy <https://galaxy.ansible.com/>`_ page. It will appear in a list of tarballs available to download.
+
+3. Add a GitHub release for the new tag. The title should be the version and content, such as - ``See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes``.
+
+  .. note::
+
+    The data for this release is only contained in a tag, and not in a branch, in particular not in ``stable-X``.
+    This is deliberate, since the next minor release ``X.(Y+1).0`` already contains the changes for ``X.Y.Z`` as well, since these were cherry-picked from ``stable-X``.
+
+
+4. Announce the release through the `Bullhorn Newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_.
+
+5. Announce the release in the pinned release issue/community pinboard of the collection and in the ``#ansible-community`` `Matrix/IRC channel <https://docs.ansible.com/ansible/devel/community/communication.html#real-time-chat>`.
+
+
+Releasing when no more minor versions are expected
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. In the ``stable-X`` branch, make sure that ``galaxy.yml`` contains the correct version number ``X.Y.Z``. If not, update it!
+
+2. In the ``stable-X`` branch, add a changelog fragment ``changelogs/fragments/X.Y.Z.yml`` with content:
+
+  .. code-block:: yaml
+
+    release_summary: |-
+      Write some text here that should appear as the release summary for this version.
+      The format is reStructuredText, but not a list as for regular changelog fragments.
+      This text will be inserted into the changelog.
+
+
+3. Generate the changelogs in the ``stable-X`` branch.
+
+  .. code-block:: bash
+
+   antsibull-changelog release
+
+
+4. In the ``stable-X`` branch, verify that ``CHANGELOG.rst`` looks as expected.
+
+5. In the ``stable-X`` branch, add, commit, and push changes to ``CHANGELOG.rst`` and ``changelogs/changelog.yaml``, and potentially deleted/archived fragments to the **upstream** repository, NOT to the origin.
+
+**Publishing the collection**
+
+
+1. In the ``stable-X`` branch, add an annotated tag to the last commit with the collection version ``X.Y.Z``. Pushing this tag to the ``upstream`` repository will make Zuul publish the collection on `Ansible Galaxy <https://galaxy.ansible.com/>`_.
+
+  .. code-block:: bash
+
+   git tag -n    # see current tags and their comments
+   git tag -a NEW_VERSION -m "comment here"    # the comment can be, for example, "community.foo: 2.1.1"
+   git push upstream NEW_VERSION
+
+
+2. Wait until the new version is published on the collection's `Ansible Galaxy <https://galaxy.ansible.com/>`_ page. It will appear in a list of tarballs available to download.
+
+3. Add a GitHub release for the new tag. Title should be the version and content, such as: ``See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes``.
+
+4. Announce the release through the `Bullhorn Newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_.
+
+5. Announce the release in the pinned issue/community pinboard of the collection and in the ``#ansible-community`` `Matrix/IRC channel <https://docs.ansible.com/ansible/devel/community/communication.html#real-time-chat>`_.

docs/docsite/rst/community/collection_contributors/collection_release_without_branches.rst

@@ -0,0 +1,115 @@
+
+.. _collection_release_without_branches:
+
+Releasing collections without release branches
+===============================================
+
+Since no release branches are used, this section does not distinguish between releasing a major, minor, or patch version.
+
+.. contents::
+  :local:
+
+Release planning and announcement
+----------------------------------
+
+#. Examine the collection to determine if there are merged changes to release.
+
+#. According to the changes made, choose an appropriate release version number. Keep in mind that the collections must follow the `semantic versioning <https://semver.org/>`_ rules. See :ref:`collection_versioning_and_deprecation` for details.
+
+#. Announce your intention to release the collection in a corresponding pinned release issue or community pinboard of the collection and in the ``community`` :ref:`Matrix/IRC channel <communication_irc>`.
+
+Creating the release branch
+----------------------------
+
+1. Ensure you are in a default branch in your local fork. We use ``main`` in the following examples.
+
+  .. code:: bash
+
+    git status
+    git checkout main     # if needed
+
+
+2. Update your local fork:
+
+  .. code:: bash
+
+    git pull --rebase upstream main
+
+
+3. Checkout a new release branch from the default branch:
+
+  .. code:: bash
+
+    git checkout -b release_branch
+
+4. Ensure the ``galaxy.yml`` contains the correct release version number.
+
+
+Generating the changelog
+-------------------------
+
+1. Add a changelog fragment ``changelogs/fragments/X.Y.Z.yml`` with content:
+
+  .. code:: yaml
+
+   release_summary: |-
+     Write some text here that should appear as the release summary for this version.
+     The format is reStructuredText, but not a list as for regular changelog fragments.
+     This text will be inserted into the changelog.
+
+  For example:
+
+  .. code:: yaml
+
+    release_summary: |-
+      This is the minor release of the ``community.mysql`` collection.
+      This changelog contains all changes to the modules and plugins in this collection
+      that have been made after the previous release.
+
+
+2. If the content was recently moved from another collection (for example, migrating a module from one collection to another), ensure you have all related changelog fragments in the ``changelogs/fragments`` directory. If not, copy them previously.
+
+3. Run ``antsibull-changelog release --reload-plugins`` . This package should previously be installed with ``pip install antsibull-changelog``.
+
+4. Verify that the ``CHANGELOG.rst`` looks as expected.
+
+5. Commit and push changes to the ``CHANGELOG.rst`` and ``changelogs/changelog.yaml``, and potentially deleted/archived fragments to the ``origin`` repository's ``release_branch``.
+
+  .. code:: bash
+
+    git commit -a -m "Release VERSION commit"
+    git push origin release_branch
+
+
+6. Create a pull request in the collection repository. If CI tests pass, merge it.
+
+7. Checkout the default branch and pull the changes:
+
+  .. code:: bash
+
+    git checkout main
+    git pull --rebase upstream main
+
+
+Publish the collection
+-----------------------------------
+
+1. Add an annotated tag to the release commit with the collection version. Pushing this tag to the ``upstream`` repository will make Zuul publish the collection on `Ansible Galaxy <https://galaxy.ansible.com/>`_.
+
+  .. code:: bash
+
+    git tag -n    # see current tags and their comments
+    git tag -a NEW_VERSION -m "comment here"    # the comment can be, for example,  "community.postgresql: 1.2.0"
+    git push upstream NEW_VERSION
+
+
+
+2. Wait until the new version is published on the collection's `Ansible Galaxy <https://galaxy.ansible.com/>`_ page. It will appear in a list of tarballs available to download.
+
+3. Update the version in the ``galaxy.yml`` file to the next **expected** version. Add, commit, and push to the ``upstream``'s default branch.
+
+4. Add a GitHub release for the new tag. Title should be the version and content ``See https://github.com/ansible-collections/community.xxx/blob/main/CHANGELOG.rst for all changes``.
+
+5. Announce the release through the `Bullhorn Newsletter issue <https://github.com/ansible/community/wiki/News#the-bullhorn>`_.
+
+6. Announce the release in the pinned release issue/community pinboard of the collection mentioned in step 3 and in the ``community`` :ref:`Matrix/IRC channel <communication_irc>`.

docs/docsite/rst/community/collection_contributors/collection_releasing.rst

@@ -0,0 +1,106 @@
+
+.. _releasing_collections:
+.. _Releasing:
+
+Releasing collections
+======================
+
+Collection maintainers release all supported stable versions of the collections regularly,
+provided that there have been enough changes merged to release.
+
+
+.. contents::
+  :local:
+
+Preparing to release a collection
+--------------------------------------------
+
+
+The collections under the `ansible-collections organization <https://github.com/ansible-collections>`_ follow  `semantic versioning <https://semver.org/>`_ when releasing. See  :ref:`collection_versioning_and_deprecation` for details.
+
+To prepare for a release, a collection must have:
+
+* A publicly available policy of releasing, versioning, and deprecation. This can be, for example, written in its README or in a dedicated pinned issue.
+* A pinned issue when its release managers inform the community about planned or completed releases. This can be combined with the release policy issue mentioned above.
+* A :ref:`changelog <collection_changelogs>`.
+* Releases of the collection tagged in the collection's repository.
+* CI pipelines up and running. This can be implemented by using GitHub Actions, Azure Pipelines, Zuul.
+* All CI tests running against a commit that releases the collection. If they do not pass, the collection MUST NOT be released.
+
+See :ref:`including_collection_ansible` if you plan on adding a new collection to the Ansible package.
+
+.. note:: 
+  
+  Your collection must pass ``ansible-test sanity`` tests. See :ref:`testing_collections` for details.
+
+
+.. _collection_versioning_and_deprecation:
+
+Collection versioning and deprecation
+--------------------------------------
+
+.. note::
+
+	Collections MUST adhere to `semantic versioning <https://semver.org/>`_.
+
+To preserve backward compatibility for users, every Ansible minor version series (5.1.x, 5.2.x, and so on) will keep the major version of a collection constant. For example, if  Ansible 5.0.0 includes ``community.general`` 4.0.2, then each Ansible 5.X.x release will include the latest ``community.general`` 4.y.z release available at build time. Ansible 5.x.x will **never** include a ``community.general`` 5.y.x release, even if it is available. Major collection version changes will be included in the next Ansible major release (6.0.0 in this case).
+Ensure that the current major release of your collection included in 6.0.0 receives at least bugfixes as long as new Ansible 6.X.X releases are produced.
+
+Since new minor releases are included, you can include new features, modules and plugins. You must make sure that you do not break backwards compatibility. See `semantic versioning <https://semver.org/>`_. for more details. This means in particular:
+
+* You can fix bugs in **patch** releases but not add new features or deprecate things.
+* You can add new features and deprecate things in **minor** releases, but not remove things or change behavior of existing features.
+* You can only remove things or make breaking changes in **major** releases.
+
+Ensure that if a deprecation is added in a collection version that is included in 5.x.y, the removal itself will only happen in a collection version included in 7.0.0 or later.
+Ensure that the policy of releasing, versioning, and deprecation is announced to contributors and users in some way. For an example of how to do this, see `the announcement in community.general <https://github.com/ansible-collections/community.general/issues/582>`_. You could also do this in the collection README file.
+
+.. _collection_changelog:
+
+Collection changelogs
+----------------------
+
+Collections MUST include a changelog. To give a consistent feel for changelogs across collections and ensure changelogs exist for collections included in the ``ansible`` package, we suggest you use `antsibull-changelog <https://github.com/ansible-community/antsibull-changelog>`_ to maintain and generate this.
+
+Before releasing, verify the following for your changelogs:
+
+* All merged pull requests since the last release, except ones related to documentation and new modules/plugins, have :ref:`changelog fragments <collection_changelog_fragments>`.
+* New module and plugin pull requests, except jinja2 test and filter plugins, do **not** need a changelog fragment, they are auto-detected by the changelog generator by their ``version_added`` value.
+* All the fragments follow the :ref:`changelog entry format <collection_changelogs_how_to_format>`.
+
+Options for releasing a collection
+-----------------------------------
+
+There are several approaches on how to release a collection. If you are not aware of which approach to use, ask in the ``#ansible-community`` IRC channel or the ``community`` Matrix channel.
+
+This section assumes that publishing the collection is done with `Zuul <https://github.com/ansible/project-config>`_ and that `antsibull-changelog <https://github.com/ansible-community/antsibull-changelog>`_ is used for the changelog.
+
+Releasing without release branches
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use releasing without release branches when:
+
+* There are no prior major releases of the collection.
+* There are no breaking changes introduced since the ``1.0.0`` release of the collection.
+
+See :ref:`collection_release_without_branches` for details.
+
+When there is a need to introduce breaking changes, you can switch to the next approach.
+
+Hybrid approach
+^^^^^^^^^^^^^^^^^^^^^
+
+In this approach, releases for the current major version are made from the ``main`` branch, while new releases for older major versions are made from release branches for these versions.
+
+Releasing with release branches
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use releasing with release branches when breaking changes have been introduced. This approach is usually only used by the large community collections, ``community.general`` and ``community.network``.
+
+See :ref:`collection_release_with_branches` for details.
+
+.. toctree::
+   :maxdepth: 1
+
+   collection_release_without_branches
+   collection_release_with_branches

docs/docsite/rst/community/collection_development_process.rst

@@ -66,6 +66,8 @@ More precisely:
 
 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.
 
+.. _collection_changelogs_how_to_format:
+
 Creating a changelog fragment
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/docsite/rst/community/contributions_collections.rst

@@ -11,10 +11,10 @@ Ansible Collections Contributor Guide
    reporting_collections
    create_pr_quick_start
    collection_contributors/test_index
-   documentation_contributions
    maintainers
    contributing_maintained_collections
    steering/steering_index
+   documentation_contributions
    other_tools_and_programs
 
 

docs/docsite/rst/community/maintainers.rst

@@ -11,6 +11,7 @@ Thank you for being a community collection maintainer. This guide offers an over
 
    maintainers_guidelines
    maintainers_workflow
+   collection_contributors/collection_releasing
 
 In addition to the information here, module maintainers should be familiar with:
 

docs/docsite/rst/community/maintainers_guidelines.rst

@@ -66,7 +66,7 @@ The quarterly Ansible Contributor Summit is a global event that provides our con
 Weekly community Matrix/IRC meetings
 ------------------------------------
 
-The Community and the Steering Committee come together at weekly meetings in the ``#ansible-community`` :ref:`Matrix/Libera.Chat <https://docs.ansible.com/ansible/devel/community/communication.html#real-time-chat>` channel to discuss important project-scale questions. See the `schedule <https://github.com/ansible/community/blob/main/meetings/README.md#schedule>`_ and join.
+The Community and the Steering Committee come together at weekly meetings in the ``#ansible-community`` :ref:`Matrix/Libera.Chat <communication_irc>` channel to discuss important project-scale questions. See the `schedule <https://github.com/ansible/community/blob/main/meetings/README.md#schedule>`_ and join.
 
 Expanding the collection community
 ===================================

docs/docsite/rst/community/maintainers_workflow.rst

@@ -1,20 +1,5 @@
 .. _maintainers_workflow:
 
-.. _Releasing:
-
-Releasing collections
-======================
-
-Collection maintainers release all supported stable versions of the collections regularly,
-provided that there have been enough changes merged to release.
-
-Generally, releasing in the collections consists of:
-
-1. Planning and announcement.
-2. Generating a changelog.
-3. Creating a release git tag and pushing it.
-4. Automatic publishing the release tarball on `Ansible Galaxy <https://galaxy.ansible.com/>`_ by `Zuul <https://dashboard.zuul.ansible.com/t/ansible/builds?pipeline=release>`_.
-5. Final announcement.
 
 Backporting and Ansible inclusion
 ==================================
@@ -59,6 +44,20 @@ For more information about the collection bot and its interface,
 see to the `Collection bot overview <https://github.com/ansible-community/collection_bot/blob/main/ISSUE_HELP.md>`_.
 
 
+Releasing a collection
+----------------------
+
+Collection maintainers are responsible for releasing new versions of a collection. Generally, releasing in the collections consists of:
+
+#. Planning and announcement.
+#. Generating a changelog.
+#. Creating a release git tag and pushing it.
+#. Automaticly publishing the release tarball on `Ansible Galaxy <https://galaxy.ansible.com/>`_ through the `Zuul dashboard <https://dashboard.zuul.ansible.com/t/ansible/builds?pipeline=release>`_.
+#. Final announcement.
+#. Optionally, `file a request to include a new collection into the Ansible package <https://github.com/ansible-collections/ansible-inclusion>`_.
+
+See :ref:`releasing_collections` for details.
+
 .. _Backporting:
 
 Backporting
@@ -72,10 +71,12 @@ The manual backport process is similar to the :ref:`ansible-core backporting gui
 For convenience, backporting can be implemented automatically using GitHub bots (for example, with the `Patchback app <https://github.com/apps/patchback>`_) and labeling as it is done in `community.general <https://github.com/ansible-collections/community.general>`_ and `community.network <https://github.com/ansible-collections/community.network>`_.
 
 
-Inclusion in Ansible
+.. _including_collection_ansible:
-----------------------
+
+Including a collection in Ansible
+-----------------------------------
 
-If a collection is not included in Ansible (not shipped with Ansible package), maintainers can submit the collection for inclusion by creating a discussion under `ansible-collections/ansible-inclusion repository <https://github.com/ansible-collections/ansible-inclusion>`_. For more information, see the `repository's README <https://github.com/ansible-collections/ansible-inclusion/blob/main/README.md>`_.
+If a collection is not included in Ansible (not shipped with Ansible package), maintainers can submit the collection for inclusion by creating a discussion under `ansible-collections/ansible-inclusion repository <https://github.com/ansible-collections/ansible-inclusion>`_. For more information, see the `repository's README <https://github.com/ansible-collections/ansible-inclusion/blob/main/README.md>`_, and the `Ansible community package collections requirements <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst>`.
 
 Stepping down as a collection maintainer
 ===========================================

docs/docsite/sphinx_conf/core_conf.py

@@ -111,6 +111,9 @@ exclude_patterns = [
     'community/reporting_collections.rst',
     'community/contributing_maintained_collections.rst',
     'community/collection_development_process.rst',
+    'community/collection_contributors/collection_release_without_branches.rst',
+    'community/collection_contributors/collection_release_with_branches.rst',
+    'community/collection_contributors/collection_releasing.rst',
     'community/maintainers_guidelines.rst',
     'community/maintainers_workflow.rst',
     'community/steering/community_steering_committee.rst',