centersl/ansible-docs
1
0
Fork 0
mirror of https://github.com/ansible/ansible-documentation.git synced 2026-03-26 13:18:58 +07:00
Code Issues Packages Projects Releases Wiki Activity

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

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

* Misc fixes
This commit is contained in:
Andrew Klychkov
2025-07-16 13:21:54 +02:00
committed by GitHub
parent cad6ff6202
commit 06427c38a4
1 changed files with 38 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
docs/docsite/rst/community/maintainers_guidelines.rst
View File

@@ -3,12 +3,12 @@
Maintainer responsibilities
===========================
This document is intended for:
This document provides guidance for:
* Contributors to collections who are interested in joining their maintainer teams.
* Collection maintainers who want to learn more about the subject.
* Contributors to collections who want to join maintainer teams.
* Collection maintainers seeking to understand their roles better.
This document explains what a collection maintainer is, outlines their responsibilities, and describes the process for becoming one.
This document defines the role of an Ansible collection maintainer, outlines their responsibilities, and describes the process for becoming one.
.. contents::
:depth: 1
@@ -17,85 +17,82 @@ This document explains what a collection maintainer is, outlines their responsib
Collection maintainer definition
--------------------------------
An Ansible collection maintainer (or maintainer for short) is a contributor who:
An Ansible collection maintainer, or simply maintainer, is a contributor who:
* Makes significant and regular contributions to the project.
* Has shown themselves as a specialist in the area the collection automates.
* Trusted by the community: to be able to perform their duties, maintainers have the ``write`` or higher access level in the collection.
* 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.
Maintainer responsibilities
---------------------------
Collection maintainers:
Collection maintainers perform the following tasks:
* Act in accordance with the :ref:`code_of_conduct`.
* Subscribe to the repository they maintain (click :guilabel:`Watch > All activity` in GitHub).
* Keep README, development guidelines, and other general :ref:`maintainer_documentation` relevant.
* Review using the :ref:`review_checklist` and commit changes made by other contributors.
* 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 that the collection adhere 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) and update the collection accordingly.
* :ref:`Build a healthy community <expanding_community>` to increase the number of active contributors and maintainers around collections.
* 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.
Multiple maintainers can divide responsibilities among each other.
Multiple maintainers can divide these responsibilities among themselves.
Becoming a maintainer
---------------------
If you are interested in becoming a maintainer and satisfy the :ref:`requirements<maintainer_requirements>`, please nominate yourself. You can also nominate another person:
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:
1. Create a GitHub issue in the relevant repository.
2. If there is no response, message the `Red Hat Ansible Community Engineering Team <https://forum.ansible.com/g/CommunityEngTeam>`_ on the `Ansible forum <https://forum.ansible.com/>`_.
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/>`_.
Communicating as a maintainer
-----------------------------
Maintainers communicate with the community through channels listed in the :ref:`Ansible communication guide<communication>`.
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.
As a maintainer, you can use the following techniques to establish communication for your 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>`_ and tags that suit your project and join the conversation.
* Find and join an existing `forum group <https://forum.ansible.com/g>`_ and use tags that suit your project.
* If nothing suits, `request them <https://forum.ansible.com/t/working-groups-things-you-can-ask-for/175>`_.
* If no suitable options exist, `request them <https://forum.ansible.com/t/working-groups-things-you-can-ask-for/175>`_.
* 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 appropriate tags.
* 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.
Participating in community topics
---------------------------------
The Community and the :ref:`Steering Committee <steering_responsibilities>` asynchronously discuss and vote on the :ref:`community topics<creating_community_topic>`.
The topics impact the whole project or its parts including collections and packaging.
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.
Share your opinion and vote on the topics to help the community make the best decisions.
Share your opinion and vote on the topics to help the community make informed decisions.
.. _expanding_community:
Expanding the collection community
==================================
Here are some ways you can expand the community around your collection:
You can expand the community around your collection in the following ways:
* Have it explicitly in your ``README`` that the collection welcomes new maintainers and contributors.
* 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/subscribe to tags related to your project.
* Have :ref:`good documentation <maintainer_documentation>` with guidelines for new contributors.
* Make people feel welcome personally and individually. Greet and thanks them.
* Use labels to show easy fixes and leave non-critical easy fixes to newcomers.
* 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 contributor documentation references in your ``README``.
* Be responsive in issues, pull requests (or PRs for short) and other communication channels.
* 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 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.
* 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.
* Look for new maintainers among active contributors.
@@ -104,7 +101,7 @@ Here are some ways you can expand the community around your collection:
Maintaining good collection documentation
=========================================
Look after the collection documentation to ensure:
Ensure the collection documentation meets these criteria:
* It is up-to-date.
* It matches the :ref:`style_guide`.
@@ -112,4 +109,4 @@ Look after the collection documentation to ensure:
* 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 the details or links to the details on how a new or continuing contributor can contribute to your collection.
* The ``CONTRIBUTING`` file includes all details or links to details on how new or continuing contributors can contribute to your collection.