community/maintainers_guidelines.rst: improve the document. Assisted-by: Gemini (#2808) (#2829)

* community/maintainers_guidelines.rst: improve the document. Assisted-by: Gemini

* Misc fixes

(cherry picked from commit 06427c3)

Author: Andersson007

docs/docsite/rst/community/maintainers_guidelines.rst

@@ -3,159 +3,110 @@
 Maintainer responsibilities
 ===========================
 
+This document provides guidance for:
+
+* Contributors to collections who want to join maintainer teams.
+* Collection maintainers seeking to understand their roles better.
+
+This document defines the role of an Ansible collection maintainer, outlines their responsibilities, and describes the process for becoming one.
+
 .. contents::
    :depth: 1
    :local:
 
-An Ansible collection maintainer is a contributor trusted by the community who makes significant and regular contributions to the project and who has shown themselves as a specialist in the related area.
-Collection maintainers have :ref:`extended permissions<collection_maintainers>` in the collection scope.
-
-Ansible collection maintainers provide feedback, responses, or actions on pull requests or issues to the collection(s) they maintain in a reasonably timely manner. They can also update the contributor guidelines for that collection, in collaboration with the Ansible community team and the other maintainers of that collection.
+Collection maintainer definition
+--------------------------------
 
-In general, collection maintainers:
+An Ansible collection maintainer, or simply maintainer, is a contributor who:
 
-- Act in accordance with the :ref:`code_of_conduct`.
-- Subscribe to the collection repository they maintain (click :guilabel:`Watch > All activity` in GitHub).
-- Keep README, development guidelines, and other general collections :ref:`maintainer_documentation` relevant.
-- Review and commit changes made by other contributors.
-- :ref:`Backport <Backporting>` changes to stable branches.
-- Address or assign issues to appropriate contributors.
-- :ref:`Release collections <Releasing>`.
-- Ensure that collections adhere to the :ref:`collections_requirements`.
-- Track changes announced in `News for collection contributors and maintainers <https://github.com/ansible-collections/news-for-maintainers>`_ and update a collection in accordance with these changes.
-- Subscribe and submit news to the  `Bullhorn newsletter <https://forum.ansible.com/c/news/bullhorn/17>`_.
-- :ref:`Build a healthy community <expanding_community>` to increase the number of active contributors and maintainers around collections.
-- Revise these guidelines to improve the maintainer experience for yourself and others.
+* Makes significant and regular contributions to a project.
+* Demonstrates expertise in the area the collection automates.
+* Earns the community's trust. To fulfill their duties, maintainers have ``write`` or higher access to the collection.
 
-Multiple maintainers can divide responsibilities among each other.
-
-How to become a maintainer
---------------------------
+Maintainer responsibilities
+---------------------------
 
-A person interested in becoming a maintainer and satisfying the :ref:`requirements<maintainer_requirements>` may either self-nominate or be nominated by another maintainer.
+Collection maintainers perform the following tasks:
 
-To nominate a candidate, create a GitHub issue in the relevant collection repository. If there is no response, the repository is not actively maintained, or the current maintainers do not have permissions to add the candidate, Create a topic in the `Ansible community forum <https://forum.ansible.com/>`_.
+* Act in accordance with the :ref:`code_of_conduct`.
+* Subscribe to the repository they maintain. In GitHub, click :guilabel:`Watch > All activity`.
+* Keep the ``README``, development guidelines, and other general :ref:`maintainer_documentation` current.
+* Review and commit changes from other contributors using the :ref:`review_checklist`.
+* :ref:`Backport <Backporting>` changes to stable branches.
+* :ref:`Plan and perform releases <Releasing>`.
+* Ensure the collection adheres to the :ref:`collections_requirements`.
+* Track changes announced through the `news-for-maintainers <https://forum.ansible.com/tag/news-for-maintainers>`_ forum tag. Click the ``Bell`` button to subscribe. Update the collection accordingly.
+* :ref:`Build a healthy community <expanding_community>` to increase the number of active contributors and maintainers for collections.
 
-Communicating as a collection maintainer
------------------------------------------
+Multiple maintainers can divide these responsibilities among themselves.
 
- Maintainers are highly encouraged to subscribe to the `"Changes impacting collection contributors and maintainers" GitHub repo <https://github.com/ansible-collections/news-for-maintainers>`_ and the `Bullhorn newsletter <https://forum.ansible.com/c/news/bullhorn/17>`_. If you have something important to announce through the newsletter (for example, recent releases), see the Bullhorn to learn how.
+Becoming a maintainer
+---------------------
 
+If you are interested in becoming a maintainer and meet the :ref:`requirements<maintainer_requirements>`, nominate yourself. You can also nominate another person by following these steps:
 
-Collection contributors and maintainers can also communicate through:
+1. Create a GitHub issue in the relevant repository.
+2. If you receive no response, message the `Red Hat Ansible Community Engineering Team <https://forum.ansible.com/g/CommunityEngTeam>`_ on the `Ansible forum <https://forum.ansible.com/>`_.
 
-* Real-time chats and forum topics appropriate to their collection, or if none exists, the general community and developer chat channels.
-* Collection project boards, issues, and GitHub discussions in corresponding repositories.
-* Contributor Summits and Ansible community days.
-* Ansiblefest and local meetups.
+Communicating as a maintainer
+-----------------------------
 
-See :ref:`communication` for more details on these communication channels.
+Maintainers communicate with the community through the channels listed in the :ref:`Ansible communication guide<communication>`.
 
 .. _wg_and_real_time_chat:
 
 Establishing working group communication
 ----------------------------------------
 
-Working groups depend on efficient communication.
-Project maintainers can use the following techniques to establish communication for working groups:
+Working groups rely on efficient communication. As a maintainer, you can establish communication for your working groups using these techniques:
 
-* Find an existing `forum group <https://forum.ansible.com/g>`_ or :ref:`working group<working_group_list>` that is similar to your project and join the conversation.
-* `Request <https://github.com/ansible/community/blob/main/WORKING-GROUPS.md>`_ a new working group for your project.
-* `Create <https://hackmd.io/@ansible-community/community-matrix-faq#How-do-I-create-a-public-community-room>`_ a public chat for your working group or `ask in the forum for help <https://forum.ansible.com/c/project/7>`_.
-* Provide working group details and links to chat rooms in the contributor section of your project ``README.md``.
-* Encourage contributors to join the forum group and chat.
+* Find and join an existing `forum group <https://forum.ansible.com/g>`_ and use tags that suit your project.
 
-See the :ref:`Communication guide <communication_irc>` to learn more about real-time chat.
+  * If no suitable options exist, `request them <https://forum.ansible.com/t/working-groups-things-you-can-ask-for/175>`_.
 
-Community Topics
-----------------
+* Provide working group details and chat room links in the contributor section of your project's ``README.md``.
+* Encourage contributors to join the forum group and use appropriate tags.
 
-The Community and the :ref:`Steering Committee <steering_responsibilitie>` asynchronously discuss and vote on the :ref:`community topics<creating_community_topic>` which impact the whole project or its parts including collections and packaging.
+Participating in community topics
+---------------------------------
 
-Share your opinion and vote on the topics to help the community make the best decisions.
+The Community and the :ref:`Steering Committee <steering_responsibilities>` discuss and vote on :ref:`community topics<creating_community_topic>` asynchronously. These topics impact the entire project or its components, including collections and packaging.
 
-.. _expanding_community:
+Share your opinion and vote on the topics to help the community make informed decisions.
 
-Contributor Summits
--------------------
-
-The quarterly Ansible Contributor Summit is a global event that provides our contributors a great opportunity to meet each other, communicate, share ideas, and see that there are other real people behind the messages on Matrix or Libera Chat IRC, or GitHub. This gives a sense of community. Watch the `Bullhorn newsletter <https://forum.ansible.com/c/news/bullhorn/17>`_ for information when the next contributor summit, invite contributors you know, and take part in the event together.
-
-Weekly community Matrix/IRC meetings
-------------------------------------
-
-The Community and the Steering Committee come together at weekly meetings in the ``#ansible-community`` `Libera.Chat IRC <https://docs.ansible.com/ansible/devel/community/communication.html#ansible-community-on-irc>`_ channel or in the bridged `#community:ansible.com <https://matrix.to/#/#community:ansible.com>`_ room on `Matrix <https://docs.ansible.com/ansible/devel/community/communication.html#ansible-community-on-matrix>`_ to discuss important project questions. Join us! Here is our `schedule <https://github.com/ansible-community/meetings/blob/main/README.md#schedule>`_.
+.. _expanding_community:
 
 Expanding the collection community
-===================================
-
-.. note::
-
-  If you discover good ways to expand a community or make it more robust, edit this section with your ideas to share with other collection maintainers.
-
-Here are some ways you can expand the community around your collection:
+==================================
 
-  * Give :ref:`newcomers a positive first experience <collection_new_contributors>`.
-  * Invite contributors to join forum groups and :ref:`real-time chats <wg_and_real_time_chat>` related to your project.
-  * Have :ref:`good documentation <maintainer_documentation>` with guidelines for new contributors.
-  * Make people feel welcome personally and individually.
-  * Use labels to show easy fixes and leave non-critical easy fixes to newcomers and offer to mentor them.
-  * Be responsive in issues, PRs and other communication.
-  * Conduct PR days regularly.
-  * Maintain a zero-tolerance policy towards behavior violating the :ref:`code_of_conduct`.
-  * Put information about how people can register code of conduct violations in your ``README`` and ``CONTRIBUTING`` files.
-  * Include quick ways contributors can help and other documentation in your ``README``.
-  * Add and keep updated the ``CONTRIBUTORS`` and ``MAINTAINERS`` files.
-  * Create a pinned issue to announce that the collection welcomes new maintainers and contributors.
-  * Look for new maintainers among active contributors.
-  * Announce that your collection welcomes new maintainers.
-  * Take part and congratulate new maintainers in Contributor Summits.
+You can expand the community around your collection in the following ways:
 
+* Explicitly state in your ``README`` that the collection welcomes new maintainers and contributors.
+* Give :ref:`newcomers a positive first experience <collection_new_contributors>`.
+* Invite contributors to join forum groups and subscribe to tags related to your project.
+* Maintain :ref:`good documentation <maintainer_documentation>` with guidelines for new contributors.
+* Make people feel welcome personally and individually. Greet and thank them.
+* Use labels to identify easy fixes and leave non-critical easy fixes to newcomers.
+* Offer help explicitly.
+* Include quick ways contributors can help and provide contributor documentation references in your ``README``.
+* Be responsive in issues, pull requests (PRs), and other communication channels.
+* Conduct PR days regularly.
+* Maintain a zero-tolerance policy toward behavior that violates the :ref:`code_of_conduct`.
+  * Include information about how people can report code of conduct violations in your ``README`` and ``CONTRIBUTING`` files.
 
-.. _collection_new_contributors:
-
-Encouraging new contributors
------------------------------
-
-Easy-fix items are the best way to attract and mentor new contributors. You should triage incoming issues to mark them with labels such as ``easyfix``, ``waiting_on_contributor``, and ``docs``. where appropriate. Do not fix these trivial non-critical bugs yourself. Instead, mentor a person who wants to contribute.
-
-For some easy-fix issues, you could ask the issue reporter whether they want to fix the issue themselves providing the link to a quick start guide for creating PRs.
-
-Conduct pull request days regularly. You could plan PR days, for example, on the last Friday of every month when you and other maintainers go through all open issues and pull requests focusing on old ones, asking people if you can help, and so on. If there are pull requests that look abandoned (for example, there has been no response on your help offers since the previous PR day), announce that anyone else interested can complete the pull request.
-
-Promote active contributors satisfying :ref:`requirements<maintainer_requirements>` to maintainers. Revise contributors' activity regularly.
-
-If your collection found new maintainers, announce that fact in the `Bullhorn newsletter <https://forum.ansible.com/c/news/bullhorn/17>`_ and during the next Contributor Summit congratulating and thanking them for the work done. You can mention all the people promoted since the previous summit. Remember to invite the other maintainers to the Summit in advance.
-
-Some other general guidelines to encourage contributors:
-
-* Welcome the author and thank them for the issue or pull request.
-* If there is a non-crucial easy-fix bug reported, politely ask the author to fix it themselves providing a link to :ref:`collection_quickstart`.
-* When suggesting changes, try to use questions, not statements.
-* When suggesting mandatory changes, do it as politely as possible providing documentation references.
-* If your suggestion is optional or a matter of personal preference, please say it explicitly.
-* When asking for adding tests or for complex code refactoring, say that the author is welcome to ask for clarifications and help if they need it.
-* If somebody suggests a good idea, mention it or put a thumbs up.
-* After merging, thank the author and reviewers for their time and effort.
-
-See the :ref:`review_checklist` for a list of items to check before you merge a PR.
+* Look for new maintainers among active contributors.
 
 .. _maintainer_documentation:
 
 Maintaining good collection documentation
-==========================================
-
-Maintainers look after the collection documentation to ensure it matches the :ref:`style_guide`. This includes keeping the following documents accurate and updated regularly:
-
-* Collection module and plugin documentation that adheres to the :ref:`Ansible documentation format <module_documenting>`.
-* Collection user guides that follow the :ref:`Collection documentation format <collections_doc_dir>`.
-* Repository files that includes at least a ``README`` and ``CONTRIBUTING`` file.
-
-A good ``README`` includes a description of the collection, a link to the :ref:`code_of_conduct`, and details on how to contribute or a pointer to the ``CONTRIBUTING`` file. If your collection is a part of Ansible (shipped with Ansible package), highlight that fact at the top of the collection's ``README``.
-
- The ``CONTRIBUTING`` file includes all the details or links to the details on how a new or continuing contributor can contribute to this collection. The ``CONTRIBUTING`` file should include:
+=========================================
 
-* Information or links to new contributor guidelines, such as a quick start on opening PRs.
-* Information or links to contributor requirements, such as unit and integration test requirements.
+Ensure the collection documentation meets these criteria:
 
-You can optionally include a ``CONTRIBUTORS`` and ``MAINTAINERS`` file to list the collection contributors and maintainers.
+* It is up-to-date.
+* It matches the :ref:`style_guide`.
+* Collection module and plugin documentation adheres to the :ref:`Ansible documentation format <module_documenting>`.
+* Collection user guides follow the :ref:`Collection documentation format <collections_doc_dir>`.
+* Repository files include at least a ``README`` and ``CONTRIBUTING`` file.
+* The ``README`` file contains all sections from `collection_template/README.md <https://github.com/ansible-collections/collection_template/blob/main/README.md>`_.
+* The ``CONTRIBUTING`` file includes all details or links to details on how new or continuing contributors can contribute to your collection.