- ``#ansible-devel`` - For discussions on developer topics and code related to features or bugs.
- ``#ansible-meeting`` - For public community meetings. We will generally announce these on one or more of the above mailing lists. See the `meeting schedule and agenda page <https://github.com/ansible/community/blob/master/meetings/README.md>`_
@ -33,6 +35,8 @@ Review, fix, and maintain the documentation
Typos are everywhere, even in the Ansible documentation. We work hard to keep the documentation up-to-date, but you may also find out-dated examples. We offer easy ways to :ref:`report and/or fix documentation errors <community_documentation_contributions>`.
.._ansible_community_meetup:
Participate in your local meetup
================================
@ -62,10 +66,12 @@ Once you've learned about the development process and have contributed code to a
To learn more about the responsibilities of being an Ansible module maintainer, please read our :ref:`module maintainer guidelines <maintainers>`.
.._community_working_groups:
Join a working group
====================
Working groups are a way for Ansible community members to self-organize around particular topics of interest. We have working groups around various topics. To join or create a working group, please read the `Ansible working group guidelines <https://github.com/ansible/community/blob/master/WORKING-GROUPS.md>`_.
Working groups are a way for Ansible community members to self-organize around particular topics of interest. We have working groups around various topics. To join or create a working group, please read the :ref:`Ansible Working Groups<working_group_list>`.
The purpose of this guide is to teach you everything you need to know about being a contributing member of the Ansible community.
The purpose of this guide is to teach you everything you need to know about being a contributing member of the Ansible community. All types of contributions are welcome, and necessary to Ansible's continued success.
To get started, please read and understand the :ref:`code_of_conduct`, and then select one of the following topics.
This page outlines the most common situations and questions that bring readers to this section. If you prefer a traditional table of contents, there's one at the bottom of the page.
Getting started
===============
* I'm new here. Where can I find the Ansible :ref:`code_of_conduct`?
* I'd like to know what I'm agreeing to when I contribute to Ansible. Does Ansible have a :ref:`contributor_license_agreement`?
* I'd like to contribute but I'm not sure how. Are there :ref:`easy ways to contribute <how_can_i_help>`?
* I want to talk to other Ansible users. How do I find an `Ansible Meetup near me <https://www.meetup.com/topics/ansible/>`_?
* I have a question. What :ref:`Ansible email lists, IRC channels <communication>` will help me find answers?
* I want to learn more about Ansible. What can I do?
* I'd like updates about new Ansible versions. How are `new releases announced <https://groups.google.com/forum/#!forum/ansible-announce>`_?
* I want to use the current release. How do I know which :ref:`releases are current <release_schedule>`?
Going deeper
============
* I think Ansible is broken. How do I :ref:`report a bug <reporting_bugs>`?
* I need functionality Ansible doesn't offer. How do I :ref:`request a feature <request_features>`?
* I'm waiting for a particular feature. How do I see what's :ref:`planned for future Ansible Releases <roadmaps>`?
* I have a specific Ansible interest or expertise (for example, VMware, Linode, etc.). How do I get involved in a :ref:`working group <working_group_list>`?
* I'd like to participate in conversations about features and fixes. How do I review GitHub issues and pull requests?
* I found a typo or another problem on docs.ansible.com. How can I :ref:`improve the documentation <community_documentation_contributions>`?
Working with the Ansible repo
=============================
* I want to code my first changes to Ansible. How do I :ref:`set up my Python development environment <environment_setup>`?
* I'd like to get more efficient as a developer. How can I find :ref:`editors, linters, and other tools <other_tools_and_programs>` that will support my Ansible development efforts?
* I want my PR to meet Ansible's guidelines. Where can I find guidance on :ref:`coding in Ansible <developer_guide>`?
* I want to :ref:`understand the development cycle <community_development_process>`.
* I'd like to connect Ansible to a new API or other resource. How do I :ref:`contribute a group of related modules <developing_modules_in_groups>`?
* My pull request is marked ``needs_rebase``. How do I :ref:`rebase my PR <rebase_guide>`?
* I'm using an older version of Ansible and want a bug fixed in my version that's already been fixed on the ``devel`` branch. How do I :ref:`backport a bugfix PR <backport_process>`?
* I have an open pull request with a failing test. How do I learn about Ansible's :ref:`testing (CI) process <developing_testing>`?
* I'm ready to step up as a module maintainer. What are the :ref:`guidelines for maintainers <maintainers>`?
* A module I maintain is obsolete. How do I :ref:`deprecate a module <deprecating_modules>`?
Traditional Table of Contents
=============================
If you prefer to read the entire Community Guide, here's a list of the pages in order.
..toctree::
:maxdepth:2
@ -26,7 +76,7 @@ To get started, please read and understand the :ref:`code_of_conduct`, and then
..toctree::
:caption:Guidelines for specific types of contributors
@ -6,6 +6,8 @@ Reporting Bugs And Requesting Features
..contents:: Topics
.._reporting_bugs:
Reporting a bug
===============
@ -13,7 +15,7 @@ Ansible practices responsible disclosure - if this is a security-related bug, em
Ansible bugs should be reported to `github.com/ansible/ansible/issues <https://github.com/ansible/ansible/issues>`_ after
signing up for a free GitHub account. Before reporting a bug, please use the bug/issue search
to see if the issue has already been reported. This is listed on the bottom of the docs page for any module.
to see if the issue has already been reported.
Knowing your Ansible version and the exact commands you are running, and what you expect, saves time and helps us help everyone with their issues more quickly. For that reason, we provide an issue template; please fill it out as completely and as accurately as possible.
@ -25,10 +27,12 @@ When sharing YAML in playbooks, formatting can be preserved by using `code block
For multiple-file content, we encourage use of gist.github.com. Online pastebin content can expire, so it's nice to have things around for a longer term if they are referenced in a ticket.
If you are not sure if something is a bug yet, you are welcome to ask about something on the mailing list or IRC first.
If you are not sure if something is a bug yet, you are welcome to ask about something on the :ref:`mailing list or IRC first <communication>`.
As we are a very high volume project, if you determine that you do have a bug, please be sure to open the issue yourself to ensure we have a record of it. Don't rely on someone else in the community to file the bug report for you.
@ -32,7 +32,8 @@ Contributing to Ansible: subjective requirements
If your module meets our objective requirements, we'll review your code to see if we think it's clear, concise, secure, and maintainable. We'll consider whether your module provides a good user experience, helpful error messages, reasonable defaults, and more. This process is subjective, and we can't list exact standards for acceptance. For the best chance of getting your module accepted into the Ansible repo, follow our :ref:`tips for module development <developing_modules_best_practices>`.
Windows modules checklist
=========================
Other checklists
================
For a checklist and details on how to write Windows modules please see :ref:`developing_modules_general_windows`
* `Amazon development checklist <https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/cloud/amazon/GUIDELINES.md>`_.
* :ref:`Windows development checklist <developing_modules_general_windows>`.
@ -15,17 +17,19 @@ Find the task that best describes what you want to do:
* I want to :ref:`add a custom plugin or module locally <developing_locally>`.
* I want to figure out if :ref:`developing a module is the right approach <module_dev_should_you>` for my use case.
* I'm ready to start developing:
* I've read the info above, and I'm sure I want to develop a module:
* What do I need to know before I start coding?
* I want to :ref:`set up my Python development environment <environment_setup>`.
* I want to :ref:`get started writing a module <developing_modules_general>`.
* I want to :ref:`write a Windows module <developing_modules_general_windows>`.
* I want to `write an Amazon module <https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/cloud/amazon/GUIDELINES.md>`_.
* I want to :ref:`write a series of related modules <developing_modules_in_groups>` that integrate Ansible with a new product (for example, a database, cloud provider, network platform, etc.).
* I want to refine my code:
* I want to :ref:`debug my module code <debugging>`.
* I want to :ref:`test my module <developing_testing>`.
* I want to :ref:`add tests <developing_testing>`.
* I want to :ref:`document my module <module_documenting>`.
* I want to :ref:`make sure my code runs on Python 2 and Python 3 <developing_python_3>`.
@ -37,6 +41,7 @@ Find the task that best describes what you want to do:
* I want to contribute back to the Ansible project:
* I want to :ref:`understand how to contribute to Ansible <ansible_community_guide>`.
* I want to :ref:`contribute my module or plugin <developing_modules_checklist>`.
* I want to :ref:`understand the license agreement <contributor_license_agreement>` for contributions to Ansible.
John R Barker
6 years ago
committed by