From 3b0d74c14592082b4be5cf8e368e251e3bb6e6d0 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Mon, 18 Apr 2022 11:36:10 -0400 Subject: [PATCH] Add contributor path page (#77494) Co-authored-by: Emmanuel Ugwu <32464178+ugwutotheeshoes@users.noreply.github.com> --- .../rst/community/contributor_path.rst | 104 ++++++++++++++++++ docs/docsite/rst/community/how_can_I_help.rst | 11 +- docs/docsite/rst/community/index.rst | 1 + .../rst/community/maintainers_guidelines.rst | 11 +- 4 files changed, 122 insertions(+), 5 deletions(-) create mode 100644 docs/docsite/rst/community/contributor_path.rst diff --git a/docs/docsite/rst/community/contributor_path.rst b/docs/docsite/rst/community/contributor_path.rst new file mode 100644 index 00000000000..8b3b0388cea --- /dev/null +++ b/docs/docsite/rst/community/contributor_path.rst @@ -0,0 +1,104 @@ +**************** +Contributor path +**************** + +This section describes the contributor journey from the beginning to becoming a leader who helps shape the future of Ansible. You can use this path as a roadmap for your long-term participation. + +Any contribution to the project, even a small one, is very welcome and valuable. Any contribution counts, whether it's feedback on an issue, a pull request, a topic or documentation change, or a coding contribution. When you contribute regularly, your proficiency and judgment in the related area increase and, along with this, the importance of your presence in the project. + +.. contents:: + :local: + + + +Determine your area of interest +================================= + +First, determine areas that are interesting to you. Consider your current experience and what you'd like to gain. For example, if you use a specific collection, have a look there. See :ref:`how_can_i_help` for more ideas on how to help. + +Find the corresponding project +==================================== + +These are multiple community projects in the Ansible ecosystem you could contribute to: + +- `Ansible Core `_ +- `Collections `_ +- `AWX `_ +- `Galaxy `_ +- `ansible-lint `_ +- `Molecule `_ + +Learn +===== + +The required skillset depends on the area of interest and the project you'll be working on. Remember that the best way to learn is by doing. + +Specific knowledge for code developers +---------------------------------------- + +Code development requires the most technical knowledge. Let's sort out what an Ansible developer should learn. + + +You should understand at least *basics* of the following tools: + +- `Python programming language `_ +- `Git `_ +- `GitHub collaborative development model through forks and pull requests `_ + +You can learn these tools more in depth when working on your first contributions. + + +Each Ansible project has its own set of contributor guidelines. Familarize yourself with these as you prepare your first contributions. + +* :ref:`Ansible Core development `. +* :ref:`Ansible collectoin development ` and the collection-level contributor guidelines in the collection repository. + + +Making your first contribution +============================== + +You can find some ideas on how you can contribute in :ref:`how_can_i_help` and the `collection repository `_ ``README`` and ``CONTRIBUTING`` files. To make your first experience as smooth as possible, read the repository documentation carefully, then ask the repository maintainers for guidance if you have any questions. + +You can also look for GitHub issues labeled with the ``easyfix``, ``good_first_issue``, and ``docs`` labels. Add a comment on the GitHub issue to say you are looking at it and to ask for help if you need it. + +Continue to contribute +====================== + +We don't expect everybody to know everything. Start small, think big. When you contribute regularly, your proficiency and judgment in the related area will improve quickly and, along with this, the importance of your presence in the project. + +See :ref:`communication` for ways to communicate and engage with the Ansible community, including working group meetings, accessing the Bullhorn news bulletin, and upcoming contributor summits. + + +Teach others +============ + +Share your experience with other contributors through `improving documentation `, answering question from other contributors and users on `Matrix/Libera.Chat IRC `, giving advice in issues and pull requests, and discussing the `Community Topics `_. + +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. + +* `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 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`. + +For information about permission levels, see the `GitHub official documentation `_. + +Become a steering committee member +================================== + +.. note:: + + You do NOT have to be a programmer to become a steering committee member. + +The `Steering Committee ` member status reflects the highest level of trust which allows contributors to lead the project through making very important `decisions `_ for the Ansible project. The Committee members are the community leaders who shape the project's future and the future of automation in the IT world in general. + +To reach the status, as the current Committee members did before getting it, along with the things mentioned in this document, you should: + +* Subscribe to, comment on, and vote on the `Community Topics `_. +* Propose your topics. +* If time permits, join the `Community meetings `_ Note this is **NOT** a requirement. \ No newline at end of file diff --git a/docs/docsite/rst/community/how_can_I_help.rst b/docs/docsite/rst/community/how_can_I_help.rst index cf0a64c28ca..ceeea05f467 100644 --- a/docs/docsite/rst/community/how_can_I_help.rst +++ b/docs/docsite/rst/community/how_can_I_help.rst @@ -48,7 +48,10 @@ If there is no meetup near you, we are happy to help you `start one `. +All software has bugs, and Ansible is no exception. When you find a bug, you can help tremendously by telling us about it: + +* Filing :ref:`issues for ansible-core `. +* Filing :ref:`issues for collections `. If the bug you found already exists in an issue, you can help by verifying the behavior of the reported bug with a comment in that issue, or by reporting any additional information. @@ -56,16 +59,16 @@ If the bug you found already exists in an issue, you can help by verifying the b Review and submit pull requests =============================== -As you become more familiar with how Ansible works, you may be able to fix issues or develop new features yourself. If you think you have a fix for a bug in Ansible, or if you have a new feature that you would like to share with millions of Ansible users, read all about the :ref:`Ansible development process ` and and :ref:`how to contribute to collections ` to learn how to get your code accepted into Ansible. +As you become more familiar with how Ansible works, you may be able to fix issues or develop new features yourself. If you think you have a fix for a bug in Ansible, or if you have a new feature that you would like to share with millions of Ansible users, read all about the :ref:`development process ` to learn how to get your code accepted into Ansible. -Another good way to help is to review pull requests that other Ansible users have submitted. The Ansible community keeps a full list of `open pull requests by file `_, so if a particular module or plugin interests you, you can easily keep track of all the relevant new pull requests and provide testing or feedback. +Another good way to help is to review pull requests that other Ansible users have submitted. Ansible core keeps a full list of `open pull requests by file `_, so if a particular module or plugin interests you, you can easily keep track of all the relevant new pull requests and provide testing or feedback. Alternately, you can review the pull requests for any collections that interest you. Click :guilabel:`Issue tracker` on the collection documentation page to find the issues and PRs for that collection. Become a collection maintainer ============================== Once you have learned about the development process and have contributed code to a collection, we encourage you to become a maintainer of that collection. There are hundreds of modules in dozens of Ansible collections, and the vast majority of them are written and maintained entirely by members of the Ansible community. -To learn more about the responsibilities of being an Ansible module maintainer, please read our :ref:`collection maintainer guidelines `. + See :ref:`collection maintainer guidelines ` to learn more about the responsibilities of being an Ansible collection maintainer. .. _community_working_groups: diff --git a/docs/docsite/rst/community/index.rst b/docs/docsite/rst/community/index.rst index 81d394f2dea..e8ae75708bf 100644 --- a/docs/docsite/rst/community/index.rst +++ b/docs/docsite/rst/community/index.rst @@ -21,3 +21,4 @@ The purpose of this guide is to teach you everything you need to know about bein :maxdepth: 2 getting_started + contributor_path diff --git a/docs/docsite/rst/community/maintainers_guidelines.rst b/docs/docsite/rst/community/maintainers_guidelines.rst index c6843e79fa0..7a51de24f90 100644 --- a/docs/docsite/rst/community/maintainers_guidelines.rst +++ b/docs/docsite/rst/community/maintainers_guidelines.rst @@ -108,7 +108,16 @@ Promote active contributors satisfying :ref:`requirements`_ 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 preferences, 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. +* 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. .. _maintainer_documentation: