From fe84c4684333bb890956490d75c7b3e9fab1f570 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Mon, 8 Sep 2025 17:09:16 +0200 Subject: [PATCH] community/maintainers_workflow.rst: improve wording and formatting (#3008) * community/maintainers_workflow.rst: improve wording and formatting * Feedback 1 (cherry picked from commit 75e8b256e3fbc4e3bb33c73b334bdd4b0c7f1a15) --- .../rst/community/contributor_path.rst | 10 +-- .../rst/community/maintainers_workflow.rst | 88 ++++++------------- 2 files changed, 33 insertions(+), 65 deletions(-) diff --git a/docs/docsite/rst/community/contributor_path.rst b/docs/docsite/rst/community/contributor_path.rst index a5171c0af04..da9a2b07909 100644 --- a/docs/docsite/rst/community/contributor_path.rst +++ b/docs/docsite/rst/community/contributor_path.rst @@ -89,12 +89,12 @@ Become a collection maintainer If you are a code contributor to a collection, you can get extended permissions in the repository and become a maintainer. A collection maintainer is a contributor trusted by the community who makes significant and regular contributions to the project and showed themselves as a specialist in the related area. See :ref:`maintainers` for details. -For some collections that use the `collection bot `_, such as `community.general `_ and `community.network `_, you can have different levels of access and permissions. +For some collections that use the `collection bot `_, such as `community.general `_ and `community.network `_, you can have different levels of access and permissions: -* :ref:`module_maintainers` - The stage prior to becoming a collection maintainer. The file is usually a module or plugin. File maintainers have indirect commit rights. -* supershipit permissions - Similar to being a file maintainer but the scope where a maintainer has the indirect commit is the whole repository. -* ``triage`` - Access to the repository that allows contributors to manage issues and pull requests. -* ``write`` access to the repository also known as ``commit``. In other words, become a committer. This access level allows contributors to merge pull requests to the development branch as well as perform all the other activities listed in the :ref:`maintainers`. +* File-level permissions: the stage prior to becoming a collection maintainer. The file is usually a module or plugin. File maintainers have indirect commit rights. +* Supershipit permissions: similar to being a file maintainer but the scope where a maintainer has the indirect commit is the whole repository. +* Triage access to the repository: allows contributors to manage issues and pull requests. +* Write access to the repository also known as ``commit``: allows contributors to merge pull requests to the development branch as well as perform all the other activities listed in the :ref:`maintainers`. For information about permission levels, see the `GitHub official documentation `_. diff --git a/docs/docsite/rst/community/maintainers_workflow.rst b/docs/docsite/rst/community/maintainers_workflow.rst index 62c001c3fe1..eda2a871312 100644 --- a/docs/docsite/rst/community/maintainers_workflow.rst +++ b/docs/docsite/rst/community/maintainers_workflow.rst @@ -1,95 +1,63 @@ .. _maintainers_workflow: +Ansible Collection Maintenance and Workflow +=========================================== + +Each collection community can set its own rules and workflows for managing pull requests (PRs), bug reports, documentation issues, feature requests, as well as for adding and replacing maintainers. -Backporting and Ansible inclusion -================================== +Collection maintainers have ``write`` or higher access to a collection, allowing them to merge pull requests and perform other administrative tasks. -Each collection community can set its own rules and workflow for managing pull requests, bug reports, documentation issues, and feature requests, as well as adding and replacing maintainers. Maintainers review and merge pull requests following the: +Managing pull requests +---------------------- + +Maintainers review and merge PRs according to the following guidelines: * :ref:`code_of_conduct` * :ref:`maintainer_requirements` * :ref:`Committer guidelines ` * :ref:`PR review checklist` -There can be two kinds of maintainers: :ref:`collection_maintainers` and :ref:`module_maintainers`. - -.. _collection_maintainers: - -Collection maintainers ----------------------- - -Collection-scope maintainers are contributors who have the ``write`` or higher access level in a collection. They have commit rights and can merge pull requests, among other permissions. - -When a collection maintainer considers a contribution to a file significant enough -(for example, fixing a complex bug, adding a feature, providing regular reviews, and so on), -they can invite the author to become a module maintainer. - - -.. _module_maintainers: - -Module maintainers ------------------- - -Module-scope maintainers exist in collections that have the `collection bot `_, -for example, `community.general `_ -and `community.network `_. - -Being a module maintainer is the stage prior to becoming a collection maintainer. Module maintainers are contributors who are listed in ``.github/BOTMETA.yml``. The scope can be any file (for example, a module or plugin), directory, or repository. Because in most cases the scope is a module or group of modules, we call these contributors module maintainers. The collection bot notifies module maintainers when issues/pull requests related to files they maintain are created. - -Module maintainers have indirect commit rights implemented through the `collection bot `_. -When two module maintainers comment with the keywords ``shipit``, ``LGTM``, or ``+1`` on a pull request -which changes a module they maintain, the collection bot merges the pull request automatically. - -For more information about the collection bot and its interface, -see to the `Collection bot overview `_. - - Releasing a collection ---------------------- -Collection maintainers are responsible for releasing new versions of a collection. Generally, releasing a collection consists of: +Collection maintainers are responsible for releasing new collection versions. The general release process includes: -#. Planning and announcement. -#. Generating a changelog. -#. Creating a release Git tag and pushing it. -#. Automatically publishing the release tarball on `Ansible Galaxy `_ through the `Zuul dashboard `_. -#. Final announcement. -#. Optionally, `file a request to include a new collection into the Ansible package `_. +#. **Planning and announcement**: Define the release scope and communicate it. +#. **Changelog generation**: Create a comprehensive list of changes. +#. **Git tagging**: Create and push a release Git tag. +#. **Automated publication**: The release tarball is automatically published on `Ansible Galaxy `_ via the `Zuul dashboard `_ or a custom GitHub Actions workflow. +#. **Final announcement**: Communicate the successful release. -See :ref:`releasing_collections` for details. +See :ref:`releasing_collections` for more information. .. _Backporting: Backporting ------------ -Collection maintainers backport merged pull requests to stable branches -following the `semantic versioning `_ and release policies of the collections. +Collection maintainers backport merged pull requests to stable branches if they exist. This process adheres to the collection's `semantic versioning `_ and release policies. -The manual backport process is similar to the :ref:`ansible-core backporting guidelines `. - -For convenience, backporting can be implemented automatically using GitHub bots (for example, with the `Patchback app `_) and labeling as it is done in `community.general `_ and `community.network `_. +The manual backporting process mirrors the :ref:`ansible-core backporting guidelines `. +For streamlined backporting, GitHub bots like the `Patchback app `_ can automate the process through labeling, as implemented in the `community.general `_ collection. .. _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 the `ansible-collections/ansible-inclusion repository `_. For more information, see the `repository's README `_, and the :ref:`Ansible community package collections requirements `. +To include a collection in the Ansible community package, maintainers create a discussion in the `ansible-collections/ansible-inclusion repository `_. See the `submission process `_ and the :ref:`Ansible community package collections requirements ` for details. Stepping down as a collection maintainer =========================================== -Times change, and so may your ability to continue as a collection maintainer. We ask that you do not step down silently. - -If you feel you don't have time to maintain your collection anymore, you should: +If you can no longer continue as a collection maintainer, follow these steps: -- Inform other maintainers about it. -- If the collection is under the ``ansible-collections`` organization, also inform relevant :ref:`communication_irc`, the ``community`` chat channels on IRC or matrix, or by email ``ansible-community@redhat.com``. -- Look at active contributors in the collection to find new maintainers among them. Discuss the potential candidates with other maintainers or with the community team. -- If you failed to find a replacement, create a pinned issue in the collection, announcing that the collection needs new maintainers. -- Make the same announcement through the `Bullhorn newsletter `_. -- Please be around to discuss potential candidates found by other maintainers or by the community team. +1. **Inform other maintainers**: Notify your co-maintainers. +2. **Notify the community**: For collections under the ``ansible-collections`` GitHub organization, inform the relevant :ref:`communication_irc` channels, or email ``ansible-community@redhat.com``. +3. **Identify potential replacements**: Look for active contributors within the collection who could become new maintainers. Discuss these candidates with other maintainers or the `Ansible community team `_. +4. **Announce the need for maintainers (if no replacement is found)**: If you cannot find a replacement, create a pinned issue in the collection repository announcing the need for new maintainers. +5. **Post in the Bullhorn newsletter**: Make the same announcement through the `Bullhorn newsletter `_. +6. **Engage in candidate discussions**: Be available to discuss potential candidates identified by other maintainers or the community team. -Remember, this is a community, so you can come back at any time in the future. +Remember, this is a community and you are welcome to rejoin at any time.