Document how to release a collection (#77391)

Co-authored-by: Divine Odazie <dodazie@gmail.com>
pull/77466/head
Sandra McCann 3 years ago committed by GitHub
parent dce30e2577
commit 26631de88c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -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: 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: 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. - 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. - 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: To check a task:
@ -128,7 +128,7 @@ To check a task:
#. Expected return values. #. 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. 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. 4. Cover cases when the module must fail. Use the ``ignore_errors: yes`` option and check the returned message with the ``assert`` module.
Example: Example:

@ -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 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: 13. Run the tests in the Ubuntu 20.04 docker container:

@ -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>`_.

@ -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>`.

@ -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

@ -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. 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 Creating a changelog fragment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

@ -66,7 +66,7 @@ The quarterly Ansible Contributor Summit is a global event that provides our con
Weekly community Matrix/IRC meetings 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 Expanding the collection community
=================================== ===================================

@ -1,20 +1,5 @@
.. _maintainers_workflow: .. _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 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>`_. 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:
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>`_. 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 Stepping down as a collection maintainer
=========================================== ===========================================

@ -111,6 +111,9 @@ exclude_patterns = [
'community/reporting_collections.rst', 'community/reporting_collections.rst',
'community/contributing_maintained_collections.rst', 'community/contributing_maintained_collections.rst',
'community/collection_development_process.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_guidelines.rst',
'community/maintainers_workflow.rst', 'community/maintainers_workflow.rst',
'community/steering/community_steering_committee.rst', 'community/steering/community_steering_committee.rst',

Loading…
Cancel
Save