mirror of https://github.com/ansible/ansible.git
Document how to release a collection (#77391)
Co-authored-by: Divine Odazie <dodazie@gmail.com>pull/77466/head
Sandra McCann
2 years ago
committed by
GitHub
parent
dce30e2577
commit
26631de88c
@ -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
|
||||
Loading…
Reference in New Issue