Create collection maintainer's guide

docs/docsite/rst/community/committer_guidelines.rst

@@ -49,6 +49,8 @@ Roles on Core
 * :ref:`Module maintainers <maintainers>`: Module maintainers own specific modules and have indirect commit access through the current module pull request mechanisms.
 * :ref:`Collection maintainers <maintainers>`: Collection maintainers own specific collections and have commit access to them. Each collection can set its own rules for contributions.
 
+.. _committer_general_rules:
+
 General rules
 =============
 Individuals with direct commit access are entrusted with powers that allow them to do a broad variety of things--probably more than we can write down. Rather than rules, treat these as general *guidelines*, individuals with this power are expected to use their best judgement.

docs/docsite/rst/community/maintainers.rst

@@ -6,29 +6,13 @@ Guidelines for collection maintainers
 
 Thank you for being a community collection maintainer. This guide offers an overview of your responsibilities as a maintainer along with resources for additional information. The Ansible community hopes that you will find that maintaining a collection is as rewarding for you as having the collection content is for the wider community.
 
-.. contents::
-   :local:
+.. toctree::
+   :maxdepth: 1
 
-In addition to the information below, module maintainers should be familiar with:
+   maintainers_guidelines
+   maintainers_workflow
+
+In addition to the information here, module maintainers should be familiar with:
 
 * :ref:`General Ansible community development practices <ansible_community_guide>`
 * Documentation on :ref:`module development <developing_modules>`
-
-
-Maintainer responsibilities
-===========================
-
-When you contribute a module to a collection included in the ``ansible`` package, you become a maintainer for that module once it has been merged. Maintainership empowers you with the authority to accept, reject, or request revisions to pull requests on your module -- but as they say, "with great power comes great responsibility."
-
-Maintainers of Ansible collections are expected to provide feedback, responses, or actions on pull requests or issues to the collection(s) they maintain in a reasonably timely manner. You can also update the contributor guidelines for that collection, in collaboration with the Ansible community team and the other maintainers of that collection.
-
-Resources
-=========
-
-Please see :ref:`communication` for ways to contact the broader Ansible community. For maintainers, following the `ansible-devel <https://groups.google.com/forum/#!forum/ansible-devel>`_ mailing list is a great way to participate in conversations about coding, get assistance when you need it, and influence the overall direction, quality, and goals of Ansible and the collections. If you are not on this relatively low-volume list, please join us here: https://groups.google.com/forum/#!forum/ansible-devel
-
-
-Pull requests, issues, and workflow
-===================================
-
-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.

docs/docsite/rst/community/maintainers_guidelines.rst

@@ -0,0 +1,131 @@
+.. _maintainer_requirements:
+
+Maintainer responsibilities
+===========================
+
+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.
+
+In general, collection maintainers:
+
+- 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 collection :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.
+- Release collections.
+- Ensure that collections adhere to the `Collection Requirements <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst>`_,
+- 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://github.com/ansible/community/wiki/News#the-bullhorn>`_.
+- :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.
+
+Multiple maintainers can divide responsibilities among each other.
+
+How to become a maintainer
+--------------------------
+
+A person who is interested in becoming a maintainer and satisfies the :ref:`requirements<maintainer_requirements>` may either self-nominate or be nominated by another maintainer.
+
+To nominate a candidate, please 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, please create the issue in the `ansible/community <https://github.com/ansible/community>`_ repository.
+
+Communicating as a collection maintainer
+-----------------------------------------
+
+ Maintainers must subscribe to the `"Changes impacting collection contributors and maintainers" GitHub repo <https://github.com/ansible-collections/news-for-maintainers>`_ and the `Bullhorn newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_. If you have something important to announce through the newsletter (for example, recent releases ), see the `Bullhorn's wiki page <https://github.com/ansible/community/wiki/News#the-bullhorn>`_ to learn how.
+
+
+Collection contributors and maintainers should also communicate through:
+
+* :ref:`communication_irc` appropriate to their collection, or if none exist, the general community and developer chat channels
+* Mailing lists such as `ansible-announce <https://groups.google.com/d/forum/ansible-announce>`_ and `ansible-devel <https://groups.google.com/d/forum/ansible-devel>`_
+* Collection project boards, issues, and GitHub discussions in corresponding repositories
+* Quarterly Contributor Summits.
+* Ansiblefest and local meetups.
+
+See :ref:`communication` for more details on these communication channels.
+
+Community Topics
+----------------
+
+The Community and the `Steering Committee <https://github.com/ansible/community-docs/blob/main/ansible_community_steering_committee.rst>`_ asynchronously discuss and vote on the `Community Topics <https://github.com/ansible-community/community-topics/issues>`_ which impact the whole project or its parts including collections and packaging.
+
+Share your opinion and vote on the topics to help the community make the best decisions.
+
+.. _expanding_community:
+
+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 persons behind the messages on Matrix/Libera.Chat IRC or GitHub. In other words, it gives a sense of community. Watch the `Bullhorn newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_ 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`` :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.
+
+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>`.
+  * 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.
+
+
+.. _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 would like 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 quickstart guide for creating PRs.
+
+Conduct pull request days regularly. You could plan PR days, for example, in 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 is 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://github.com/ansible/community/wiki/News#the-bullhorn>`_ 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.
+
+
+
+.. _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/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 (is 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 quickstart on opening PRs.
+* Information or links to contributor requirements, such as unit and integration test requirements.
+
+You can optionally include a ``CONTRIBUTORS`` and ``MAINTAINERS`` file to list the collection contributors and maintainers.

docs/docsite/rst/community/maintainers_workflow.rst

@@ -0,0 +1,94 @@
+.. _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
+==================================
+
+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:
+
+* :ref:`code_of_conduct`
+* :ref:`maintainer_requirements`
+* :ref:`Committer guidelines <committer_general_rules>`.
+* `PR review checklist <https://github.com/ansible/community-docs/blob/main/review_checklist.rst>`_
+
+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 <https://github.com/ansible-community/collection_bot>`_,
+for example `community.general <https://github.com/ansible-collections/community.general>`_
+and `community.network <https://github.com/ansible-collections/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 <https://github.com/ansible-community/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 <https://github.com/ansible-community/collection_bot/blob/main/ISSUE_HELP.md>`_.
+
+
+.. _Backporting:
+
+Backporting
+------------
+
+Collection maintainers backport merged pull requests to stable branches
+following the `semantic versioning <https://semver.org/>`_ and release policies of the collections.
+
+The manual backport process is similar to the :ref:`ansible-core backporting guidelines <backport_process>`.
+
+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
+----------------------
+
+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>`_.
+
+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 any more, you should:
+
+- 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 <https://github.com/ansible/community/wiki/News#the-bullhorn>`_.
+- Please be around to discuss potential candidates found by other maintainers or by the community team.
+
+Remember, this is a community, so you can come back at any time in the future.

docs/docsite/sphinx_conf/core_conf.py

@@ -102,6 +102,8 @@
     'community/contributing_maintained_collections.rst',
     'community/collection_development_process.rst',
     'community/maintainers.rst',
+    'community/maintainers_guidelines.rst',
+    'community/maintainers_workflow.rst',
     'porting_guides/porting_guides.rst',
     'porting_guides/porting_guide_[1-9]*',
     'roadmap/index.rst',