diff options
author | Sandra McCann <samccann@redhat.com> | 2022-04-05 13:59:45 -0400 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-04-05 13:59:45 -0400 |
commit | 26631de88cbe99ad2b924b0f0ef90ea6c4135a52 (patch) | |
tree | 9368d749a3dfacb9d34757c99690541eede1308f | |
parent | dce30e2577cb2eeb4260d304626605e363c7ab0e (diff) | |
download | ansible-26631de88cbe99ad2b924b0f0ef90ea6c4135a52.tar.gz |
Document how to release a collection (#77391)
Co-authored-by: Divine Odazie <dodazie@gmail.com>
11 files changed, 576 insertions, 29 deletions
diff --git a/docs/docsite/rst/community/collection_contributors/collection_integration_about.rst b/docs/docsite/rst/community/collection_contributors/collection_integration_about.rst index cac6ba076d..2e2bccb192 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_integration_about.rst +++ b/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?) -- 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?) +- 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? +- 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 for real (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. 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: diff --git a/docs/docsite/rst/community/collection_contributors/collection_integration_add.rst b/docs/docsite/rst/community/collection_contributors/collection_integration_add.rst index cbb3bd920c..d91243314a 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_integration_add.rst +++ b/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: diff --git a/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst b/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst new file mode 100644 index 0000000000..b4fe739189 --- /dev/null +++ b/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>`_. diff --git a/docs/docsite/rst/community/collection_contributors/collection_release_without_branches.rst b/docs/docsite/rst/community/collection_contributors/collection_release_without_branches.rst new file mode 100644 index 0000000000..4cef33f03c --- /dev/null +++ b/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>`. diff --git a/docs/docsite/rst/community/collection_contributors/collection_releasing.rst b/docs/docsite/rst/community/collection_contributors/collection_releasing.rst new file mode 100644 index 0000000000..481208b007 --- /dev/null +++ b/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 diff --git a/docs/docsite/rst/community/collection_development_process.rst b/docs/docsite/rst/community/collection_development_process.rst index 87bd736536..416b24ffda 100644 --- a/docs/docsite/rst/community/collection_development_process.rst +++ b/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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/docsite/rst/community/contributions_collections.rst b/docs/docsite/rst/community/contributions_collections.rst index a577bb7f27..4e0d7ba934 100644 --- a/docs/docsite/rst/community/contributions_collections.rst +++ b/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 diff --git a/docs/docsite/rst/community/maintainers.rst b/docs/docsite/rst/community/maintainers.rst index b43bea0190..bef1567ce6 100644 --- a/docs/docsite/rst/community/maintainers.rst +++ b/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: diff --git a/docs/docsite/rst/community/maintainers_guidelines.rst b/docs/docsite/rst/community/maintainers_guidelines.rst index 7d3ca609c2..c6843e79fa 100644 --- a/docs/docsite/rst/community/maintainers_guidelines.rst +++ b/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 =================================== diff --git a/docs/docsite/rst/community/maintainers_workflow.rst b/docs/docsite/rst/community/maintainers_workflow.rst index 926043ec42..37d1179553 100644 --- a/docs/docsite/rst/community/maintainers_workflow.rst +++ b/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 =========================================== diff --git a/docs/docsite/sphinx_conf/core_conf.py b/docs/docsite/sphinx_conf/core_conf.py index f03a8be04d..bd3fe06151 100644 --- a/docs/docsite/sphinx_conf/core_conf.py +++ b/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', |