partial update of community docs to reflect collections transition (#70488)
This commit is contained in:
Alicia Cozine
GitHub
parent
692e5de05e
commit
f1f782fc37
7 changed files with 97 additions and 193 deletions
|
|
@ -27,7 +27,7 @@ If you want to follow the conversation about what features will be added to Ansi
|
|||
Micro development: the lifecycle of a PR
|
||||
========================================
|
||||
|
||||
Ansible accepts code through **pull requests** ("PRs" for short). GitHub provides a great overview of `how the pull request process works <https://help.github.com/articles/about-pull-requests/>`_ in general. The ultimate goal of any pull request is to get merged and become part of Ansible Core.
|
||||
Ansible accepts code through **pull requests** ("PRs" for short). GitHub provides a great overview of `how the pull request process works <https://help.github.com/articles/about-pull-requests/>`_ in general. The ultimate goal of any pull request is to get merged and become part of a collection or ansible-base.
|
||||
Here's an overview of the PR lifecycle:
|
||||
|
||||
* Contributor opens a PR
|
||||
|
|
|
|||
|
|
@ -4,7 +4,8 @@
|
|||
How can I help?
|
||||
***************
|
||||
|
||||
.. contents:: Topics
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
Thanks for being interested in helping the Ansible project!
|
||||
|
||||
|
|
@ -50,19 +51,19 @@ File and verify issues
|
|||
All software has bugs, and Ansible is no exception. When you find a bug, you can help tremendously by :ref:`telling us about it <reporting_bugs_and_features>`.
|
||||
|
||||
|
||||
If you should discover that the bug you're trying to file 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.
|
||||
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.
|
||||
|
||||
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've got a solution to a bug you've found in Ansible, or if you've got a new feature that you've written and would like to share with millions of Ansible users, read all about the :ref:`Ansible development process <community_development_process>` 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:`Ansible development process <community_development_process>` and and :ref:`how to contribute to collections <contributing_maintained_collections>` 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 <https://ansible.sivel.net/pr/byfile.html>`_, so if there's a particular module or plug-in that particularly interests you, you can easily keep track of all the relevant new pull requests and provide testing or feedback.
|
||||
|
||||
Become a module maintainer
|
||||
==========================
|
||||
Become a collection maintainer
|
||||
==============================
|
||||
|
||||
Once you've learned about the development process and have contributed code to a particular module, we encourage you to become a maintainer of that module. There are hundreds of different modules in Ansible, and the vast majority of them are written and maintained entirely by members of the Ansible community.
|
||||
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:`module maintainer guidelines <maintainers>`.
|
||||
|
||||
|
|
@ -77,7 +78,7 @@ Working groups are a way for Ansible community members to self-organize around p
|
|||
Teach Ansible to others
|
||||
=======================
|
||||
|
||||
We're working on a standardized `Ansible workshop <https://ansible.github.io/workshops/>`_ that can provide a good hands-on introduction to Ansible usage and concepts.
|
||||
We are working on a standardized `Ansible workshop <https://ansible.github.io/workshops/>`_ that can provide a good hands-on introduction to Ansible usage and concepts.
|
||||
|
||||
Social media
|
||||
============
|
||||
|
|
|
|||
|
|
@ -14,9 +14,9 @@ This page outlines the most common situations and questions that bring readers t
|
|||
Getting started
|
||||
===============
|
||||
|
||||
* I'm new to the community. 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 am new to the community. Where can I find the Ansible :ref:`code_of_conduct`?
|
||||
* I would like to know what I am agreeing to when I contribute to Ansible. Does Ansible have a :ref:`contributor_license_agreement`?
|
||||
* I would like to contribute but I am 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. Which :ref:`Ansible email lists and IRC channels <communication>` will help me find answers?
|
||||
* I want to learn more about Ansible. What can I do?
|
||||
|
|
@ -27,7 +27,7 @@ Getting started
|
|||
* `Review getting started guides <https://www.ansible.com/resources/get-started>`_.
|
||||
* `Watch videos <https://www.ansible.com/resources/videos>`_ - includes Ansible Automates, AnsibleFest & webinar recordings.
|
||||
|
||||
* I'd like updates about new Ansible versions. How are `new releases announced <https://groups.google.com/forum/#!forum/ansible-announce>`_?
|
||||
* I would 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
|
||||
|
|
@ -36,9 +36,9 @@ Going deeper
|
|||
* I think Ansible is broken. How do I :ref:`report a bug <reporting_bugs>`?
|
||||
* I need functionality that Ansible doesn't offer. How do I :ref:`request a feature <request_features>`?
|
||||
* How do I :ref:`contribute to an Ansible-maintained collection <contributing_maintained_collections>`?
|
||||
* I'm waiting for a particular feature. How do I see what's :ref:`planned for future Ansible Releases <roadmaps>`?
|
||||
* I am waiting for a particular feature. How do I see what is :ref:`planned for future Ansible Releases <roadmaps>`?
|
||||
* I have a specific Ansible interest or expertise (for example, VMware, Linode, and so on.). 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 would 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>`?
|
||||
|
||||
|
||||
|
|
@ -46,15 +46,15 @@ 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 would 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 learn more about Ansible roadmaps, releases, and projects. How do I find information on :ref:`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>`?
|
||||
* I would like to connect Ansible to a new API or other resource. How do I :ref:`create a collection <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 am using an older version of Ansible and want a bug fixed in my version that has 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>`?
|
||||
* I am ready to step up as a collection maintainer. What are the :ref:`guidelines for maintainers <maintainers>`?
|
||||
* A module in a collection I maintain is obsolete. How do I :ref:`deprecate a module <deprecating_modules>`?
|
||||
|
||||
Traditional Table of Contents
|
||||
=============================
|
||||
|
|
|
|||
|
|
@ -1,12 +1,13 @@
|
|||
.. _maintainers:
|
||||
|
||||
****************************
|
||||
Module Maintainer Guidelines
|
||||
****************************
|
||||
********************************
|
||||
Collection maintainer guidelines
|
||||
********************************
|
||||
|
||||
.. contents:: Topics
|
||||
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.
|
||||
|
||||
Thank you for being a maintainer of part of Ansible's codebase. This guide provides module maintainers an overview of their responsibilities, resources for additional information, and links to helpful tools.
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
In addition to the information below, module maintainers should be familiar with:
|
||||
|
||||
|
|
@ -17,57 +18,17 @@ In addition to the information below, module maintainers should be familiar with
|
|||
Maintainer responsibilities
|
||||
===========================
|
||||
|
||||
When you contribute a new module to the `ansible/ansible <https://github.com/ansible/ansible>`_ repository, you become the 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."
|
||||
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 modules are expected to provide feedback, responses, or actions on pull requests or issues to the module(s) they maintain in a reasonably timely manner.
|
||||
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.
|
||||
|
||||
It is also recommended that you occasionally revisit the `contribution guidelines <https://github.com/ansible/ansible/blob/devel/.github/CONTRIBUTING.md>`_, as they are continually refined. Occasionally, you may be requested to update your module to move it closer to the general accepted standard requirements. We hope for this to be infrequent, and will always be a request with a fair amount of lead time (ie: not by tomorrow!).
|
||||
Resources
|
||||
=========
|
||||
|
||||
Finally, following the `ansible-devel <https://groups.google.com/forum/#!forum/ansible-devel>`_ mailing list can be a great way to participate in the broader Ansible community, and a place where you can influence the overall direction, quality, and goals of Ansible and its modules. If you're not on this relatively low-volume list, please join us here: https://groups.google.com/forum/#!forum/ansible-devel
|
||||
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
|
||||
|
||||
The Ansible community hopes that you will find that maintaining your module is as rewarding for you as having the module is for the wider community.
|
||||
|
||||
Pull requests, issues, and workflow
|
||||
===================================
|
||||
|
||||
Pull requests
|
||||
-------------
|
||||
|
||||
Module pull requests are located in the `main Ansible repository <https://github.com/ansible/ansible/pulls>`_.
|
||||
|
||||
Because of the high volume of pull requests, notification of PRs to specific modules are routed by an automated bot to the appropriate maintainer for handling. It is recommended that you set an appropriate notification process to receive notifications which mention your GitHub ID.
|
||||
|
||||
Issues
|
||||
------
|
||||
|
||||
Issues for modules, including bug reports, documentation bug reports, and feature requests, are tracked in the `ansible repository <https://github.com/ansible/ansible/issues>`_.
|
||||
|
||||
Issues for modules are routed to their maintainers by an automated process. This process is still being refined, and currently depends upon the issue creator to provide adequate details (specifically, providing the proper module name) in order to route it correctly. If you are a maintainer of a specific module, it is recommended that you periodically search module issues for issues which mention your module's name (or some variation on that name), as well as setting an appropriate notification process for receiving notification of mentions of your GitHub ID.
|
||||
|
||||
PR workflow
|
||||
-----------
|
||||
|
||||
Automated routing of pull requests is handled by a tool called `Ansibot <https://github.com/ansible/ansibullbot>`_.
|
||||
|
||||
Being moderately familiar with how the workflow behind the bot operates can be helpful to you, and -- should things go awry -- your feedback can be helpful to the folks that continually help Ansibullbot to evolve.
|
||||
|
||||
A detailed explanation of the PR workflow can be seen in the :ref:`community_development_process`.
|
||||
|
||||
Maintainers (BOTMETA.yml)
|
||||
-------------------------
|
||||
|
||||
The full list of maintainers is located in `BOTMETA.yml <https://github.com/ansible/ansible/blob/devel/.github/BOTMETA.yml>`_.
|
||||
|
||||
Adding and removing maintainers
|
||||
===============================
|
||||
|
||||
Communities change over time, and no one maintains a module forever. If you'd like to propose an additional maintainer for your module, please submit a PR to ``BOTMETA.yml`` with the GitHub username of the new maintainer.
|
||||
|
||||
If you'd like to step down as a maintainer, please submit a PR to the ``BOTMETA.yml`` removing your GitHub ID from the module in question. If that would leave the module with no maintainers, put "ansible" as the maintainer. This will indicate that the module is temporarily without a maintainer, and the Ansible community team will search for a new maintainer.
|
||||
|
||||
Tools and other Resources
|
||||
=========================
|
||||
|
||||
* `PRs in flight, organized by directory <https://ansible.sivel.net/pr/byfile.html>`_
|
||||
* `Ansibullbot <https://github.com/ansible/ansibullbot>`_
|
||||
* :ref:`community_development_process`
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -1,39 +1,56 @@
|
|||
.. _reporting_bugs_and_features:
|
||||
|
||||
**************************************
|
||||
Reporting Bugs And Requesting Features
|
||||
Reporting bugs and requesting features
|
||||
**************************************
|
||||
|
||||
.. contents:: Topics
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
.. _reporting_bugs:
|
||||
|
||||
Reporting a bug
|
||||
===============
|
||||
|
||||
Security bugs
|
||||
-------------
|
||||
|
||||
Ansible practices responsible disclosure - if this is a security-related bug, email `security@ansible.com <mailto:security@ansible.com>`_ instead of filing a ticket or posting to any public groups, and you will receive a prompt response.
|
||||
|
||||
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.
|
||||
Bugs in ansible-base
|
||||
--------------------
|
||||
|
||||
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.
|
||||
If you find a bug that affects multiple plugins, a plugin that remained in the ansible/ansible repo, or the overall functioning of Ansible, report it to `github.com/ansible/ansible/issues <https://github.com/ansible/ansible/issues>`_. You need a free GitHub account. Before reporting a bug, use the bug/issue search to see if the issue has already been reported. If you are not sure if something is a bug yet, you can report the behavior on the :ref:`mailing list or IRC first <communication>`.
|
||||
|
||||
Do not use the issue tracker for "how do I do this" type questions. These are great candidates for IRC or the mailing list instead where things are likely to be more of a discussion.
|
||||
Do not open issues for "how do I do this" type questions. These are great topics for IRC or the mailing list, where things are likely to be more of a discussion.
|
||||
|
||||
To be respectful of reviewers' time and allow us to help everyone efficiently, please provide minimal well-reduced and well-commented examples rather than sharing your entire production playbook. Include playbook snippets and output where possible.
|
||||
If you find a bug, open the issue yourself to ensure we have a record of it. Do not rely on someone else in the community to file the bug report for you. We have created an issue template, which saves time and helps us help everyone with their issues more quickly. Please fill it out as completely and as accurately as possible:
|
||||
|
||||
When sharing YAML in playbooks, formatting can be preserved by using `code blocks <https://help.github.com/articles/creating-and-highlighting-code-blocks/>`_.
|
||||
* Include the Ansible version
|
||||
* Include any relevant configuration
|
||||
* Include the exact commands or tasks you are running
|
||||
* Describe the behavior you expected
|
||||
* Provide steps to reproduce the bug
|
||||
* Use minimal well-reduced and well-commented examples, not your entire production playbook
|
||||
* When sharing YAML in playbooks, preserve the formatting by using `code blocks <https://help.github.com/articles/creating-and-highlighting-code-blocks/>`_.
|
||||
* Document the behavior you got
|
||||
* Include output where possible
|
||||
* For multiple-file content, use gist.github.com, which is more durable than pastebin content
|
||||
|
||||
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.
|
||||
Bugs in collections
|
||||
-------------------
|
||||
|
||||
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>`.
|
||||
Many bugs only affect a single module or plugin. If you find a bug that affects a module or plugin hosted in a collection, file the bug in the repository of the :ref:`collection <collections>`:
|
||||
|
||||
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.
|
||||
#. Find the collection on Galaxy.
|
||||
#. Click on the Issue Tracker link for that collection.
|
||||
#. Follow the contributor guidelines or instructions in the collection repo.
|
||||
|
||||
If you are not sure whether a bug is in ansible-base or in a collection, you can report the behavior on the :ref:`mailing list or IRC first <communication>`.
|
||||
|
||||
.. _request_features:
|
||||
|
||||
Requesting a feature
|
||||
====================
|
||||
|
||||
The best way to get a feature into Ansible is to :ref:`submit a pull request <community_pull_requests>`.
|
||||
The best way to get a feature into Ansible is to :ref:`submit a pull request <community_pull_requests>`, either against ansible-base or against a collection. See also :ref:`ansible_collection_merge_requirements`.
|
||||
|
|
|
|||
|
|
@ -5,7 +5,6 @@
|
|||
Developing collections
|
||||
**********************
|
||||
|
||||
|
||||
Collections are a distribution format for Ansible content. You can use collections to package and distribute playbooks, roles, modules, and plugins.
|
||||
You can publish and use collections through `Ansible Galaxy <https://galaxy.ansible.com>`_.
|
||||
|
||||
|
|
@ -653,7 +652,7 @@ To generate changelogs from the changelog fragments you created:
|
|||
|
||||
.. note::
|
||||
|
||||
Add the ``--reload-plugins`` option if you ran the ``antsibull-changelog release`` command previously and the version of the collection has not changed. ``antsibull-changelog`` caches the information on all plugins and does not update its cache until the collection version changes.
|
||||
Add the ``--reload-plugins`` option if you ran the ``antsibull-changelog release`` command previously and the version of the collection has not changed. ``antsibull-changelog`` caches the information on all plugins and does not update its cache until the collection version changes.
|
||||
|
||||
|
||||
Porting Guide entries
|
||||
|
|
|
|||
|
|
@ -1,64 +1,49 @@
|
|||
.. _developing_modules_in_groups:
|
||||
|
||||
*********************************************
|
||||
Information for submitting a group of modules
|
||||
*********************************************
|
||||
*************************
|
||||
Creating a new collection
|
||||
*************************
|
||||
|
||||
.. contents:: Topics
|
||||
Starting with Ansible 2.10, related modules should be developed in a collection. The Ansible core team and community compiled these module development tips and tricks to help companies developing Ansible modules for their products and users developing Ansible modules for third-party products. See :ref:`developing_collections` for a more detailed description of the collections format and additional development guidelines.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
Submitting a group of modules
|
||||
=============================
|
||||
|
||||
This section discusses how to get multiple related modules into Ansible.
|
||||
|
||||
This document is intended for both companies wishing to add modules for their own products as well as users of 3rd party products wishing to add Ansible functionality.
|
||||
|
||||
It's based on module development tips and tricks that the Ansible core team and community have accumulated.
|
||||
|
||||
.. include:: shared_snippets/licensing.txt
|
||||
|
||||
Before you start coding
|
||||
=======================
|
||||
|
||||
Although it's tempting to get straight into coding, there are a few things to be aware of first. This list of prerequisites is designed to help ensure that you develop high-quality modules that flow easily through the review process and get into Ansible more quickly.
|
||||
This list of prerequisites is designed to help ensure that you develop high-quality modules that work well with ansible-base and provide a seamless user experience.
|
||||
|
||||
* Read though all the pages linked off :ref:`developing_modules_general`; paying particular focus to the :ref:`developing_modules_checklist`.
|
||||
* New modules must be PEP 8 compliant. See :ref:`testing_pep8` for more information.
|
||||
* Starting with Ansible version 2.4, all new modules must :ref:`support Python 2.6+ and Python 3.5+ <developing_python_3>`. If this is an issue, please contact us (see the "Speak to us" section later in this document to learn how).
|
||||
* Have a look at the existing modules and how they've been named in the :ref:`all_modules`, especially in the same functional area (such as cloud, networking, databases).
|
||||
* Shared code can be placed into ``lib/ansible/module_utils/``
|
||||
* Shared documentation (for example describing common arguments) can be placed in ``lib/ansible/plugins/doc_fragments/``.
|
||||
* With great power comes great responsibility: Ansible module maintainers have a duty to help keep modules up to date. As with all successful community projects, module maintainers should keep a watchful eye for reported issues and contributions.
|
||||
* Although not required, unit and/or integration tests are strongly recommended. Unit tests are especially valuable when external resources (such as cloud or network devices) are required. For more information see :ref:`developing_testing` and the `Testing Working Group <https://github.com/ansible/community/blob/master/meetings/README.md>`_.
|
||||
* Starting with Ansible 2.4 all :ref:`network_modules` MUST have unit tests.
|
||||
* We encourage PEP 8 compliance. See :ref:`testing_pep8` for more information.
|
||||
* We encourage supporting :ref:`Python 2.6+ and Python 3.5+ <developing_python_3>`.
|
||||
* Look at Ansible Galaxy and review the naming conventions in your functional area (such as cloud, networking, databases).
|
||||
* With great power comes great responsibility: Ansible collection maintainers have a duty to help keep content up to date. As with all successful community projects, collection maintainers should keep a watchful eye for reported issues and contributions.
|
||||
* We strongly recommend unit and/or integration tests. Unit tests are especially valuable when external resources (such as cloud or network devices) are required. For more information see :ref:`developing_testing` and the `Testing Working Group <https://github.com/ansible/community/blob/master/meetings/README.md>`_.
|
||||
|
||||
|
||||
Naming convention
|
||||
=================
|
||||
Naming conventions
|
||||
==================
|
||||
|
||||
As you may have noticed when looking under ``lib/ansible/modules/`` we support up to two directories deep (but no deeper), e.g. `databases/mysql`. This is used to group files on disk as well as group related modules into categories and topics the Module Index, for example: :ref:`database_modules`.
|
||||
Fully Qualified Collection Names (FQCNs) for plugins and modules include three elements:
|
||||
|
||||
The directory name should represent the *product* or *OS* name, not the company name.
|
||||
* the Galaxy namespace, which generally represents the company or group
|
||||
* the collection name, which generally represents the product or OS
|
||||
* the plugin or module name
|
||||
* always in lower case
|
||||
* words separated with an underscore (``_``) character
|
||||
* singular, rather than plural, for example, ``command`` not ``commands``
|
||||
|
||||
Each module should have the above (or similar) prefix; see existing :ref:`all_modules` for existing examples.
|
||||
|
||||
**Note:**
|
||||
|
||||
* File and directory names are always in lower case
|
||||
* Words are separated with an underscore (``_``) character
|
||||
* Module names should be in the singular, rather than plural, eg ``command`` not ``commands``
|
||||
For example, ``community.mongodb.mongodb_linux`` or ``cisco.meraki.meraki_device``.
|
||||
|
||||
It is convenient if the organization and repository names on GitHub (or elsewhere) match your namespace and collection names on Ansible Galaxy, but it is not required. The plugin names you select, however, are always the same in your code repository and in your collection artifact on Galaxy.
|
||||
|
||||
Speak to us
|
||||
===========
|
||||
|
||||
Circulating your ideas before coding is a good way to help you set off in the right direction.
|
||||
|
||||
After reading the "Before you start coding" section you will hopefully have a reasonable idea of the structure of your modules.
|
||||
|
||||
We've found that writing a list of your proposed module names and a one or two line description of what they will achieve and having that reviewed by Ansible is a great way to ensure the modules fit the way people have used Ansible Modules before, and therefore make them easier to use.
|
||||
|
||||
Circulating your ideas before coding helps you adopt good practices and avoid common mistakes. After reading the "Before you start coding" section you should have a reasonable idea of the structure of your modules. Write a list of your proposed plugin and/or module names, with a short description of what each one does. Circulate that list on IRC or a mailing list so the Ansible community can review your ideas for consistency and familiarity. Names and functionality that are consistent, predictable, and familiar make your collection easier to use.
|
||||
|
||||
Where to get support
|
||||
====================
|
||||
|
|
@ -67,76 +52,23 @@ Ansible has a thriving and knowledgeable community of module developers that is
|
|||
|
||||
In the :ref:`ansible_community_guide` you can find how to:
|
||||
|
||||
* Subscribe to the Mailing Lists - We suggest "Ansible Development List" (for codefreeze info) and "Ansible Announce list"
|
||||
* ``#ansible-devel`` - We have found that IRC ``#ansible-devel`` on FreeNode's IRC network works best for module developers so we can have an interactive dialogue.
|
||||
* Subscribe to the Mailing Lists - We suggest "Ansible Development List" and "Ansible Announce list"
|
||||
* ``#ansible-devel`` - We have found that IRC ``#ansible-devel`` on FreeNode's IRC network works best for developers so we can have an interactive dialogue.
|
||||
* IRC meetings - Join the various weekly IRC meetings `meeting schedule and agenda page <https://github.com/ansible/community/blob/master/meetings/README.md>`_
|
||||
|
||||
|
||||
Your first pull request
|
||||
=======================
|
||||
|
||||
Now that you've reviewed this document, you should be ready to open your first pull request.
|
||||
|
||||
The first PR is slightly different to the rest because it:
|
||||
|
||||
* defines the namespace
|
||||
* provides a basis for detailed review that will help shape your future PRs
|
||||
* may include shared documentation (`doc_fragments`) that multiple modules require
|
||||
* may include shared code (`module_utils`) that multiple modules require
|
||||
|
||||
|
||||
The first PR should include the following files:
|
||||
|
||||
* ``lib/ansible/modules/$category/$topic/__init__.py`` - An empty file to initialize namespace and allow Python to import the files. *Required new file*
|
||||
* ``lib/ansible/modules/$category/$topic/$yourfirstmodule.py`` - A single module. *Required new file*
|
||||
* ``lib/ansible/plugins/doc_fragments/$topic.py`` - Code documentation, such as details regarding common arguments. *Optional new file*
|
||||
* ``lib/ansible/module_utils/$topic.py`` - Code shared between more than one module, such as common arguments. *Optional new file*
|
||||
|
||||
And that's it.
|
||||
|
||||
Before pushing your PR to GitHub it's a good idea to review the :ref:`developing_modules_checklist` again.
|
||||
|
||||
After publishing your PR to https://github.com/ansible/ansible, a Shippable CI test should run within a few minutes. Check the results (at the end of the PR page) to ensure that it's passing (green). If it's not passing, inspect each of the results. Most of the errors should be self-explanatory and are often related to badly formatted documentation (see :ref:`yaml_syntax`) or code that isn't valid Python 2.6 or valid Python 3.5 (see :ref:`developing_python_3`). If you aren't sure what a Shippable test message means, copy it into the PR along with a comment and we will review.
|
||||
|
||||
If you need further advice, consider join the ``#ansible-devel`` IRC channel (see how in the "Where to get support").
|
||||
|
||||
|
||||
We have a ``ansibullbot`` helper that comments on GitHub Issues and PRs which should highlight important information.
|
||||
|
||||
|
||||
Subsequent PRs
|
||||
Required files
|
||||
==============
|
||||
|
||||
By this point you first PR that defined the module namespace should have been merged. You can take the lessons learned from the first PR and apply it to the rest of the modules.
|
||||
Your collection should include the following files to be usable:
|
||||
|
||||
Raise exactly one PR per module for the remaining modules.
|
||||
* an ``__init__.py`` file - An empty file to initialize namespace and allow Python to import the files. *Required*
|
||||
* at least one plugin, for example, ``/plugins/modules/$your_first_module.py``. *Required*
|
||||
* if needed, one or more ``/plugins/doc_fragments/$topic.py`` files - Code documentation, such as details regarding common arguments. *Optional*
|
||||
* if needed, one or more ``/plugins/module_utils/$topic.py`` files - Code shared between more than one module, such as common arguments. *Optional*
|
||||
|
||||
Over the years we've experimented with different sized module PRs, ranging from one module to many tens of modules, and during that time we've found the following:
|
||||
When you have these files ready, review the :ref:`developing_modules_checklist` again. If you are creating a new collection, you are responsible for all procedures related to your repository, including setting rules for contributions, finding reviewers, and testing and maintaining the code in your collection.
|
||||
|
||||
* A PR with a single file gets a higher quality review
|
||||
* PRs with multiple modules are harder for the creator to ensure all feedback has been applied
|
||||
* PRs with many modules take a lot more work to review, and tend to get passed over for easier-to-review PRs.
|
||||
|
||||
You can raise up to five PRs at once (5 PRs = 5 new modules) **after** your first PR has been merged. We've found this is a good batch size to keep the review process flowing.
|
||||
|
||||
Maintaining your modules
|
||||
========================
|
||||
|
||||
Now that your modules are integrated there are a few bits of housekeeping to be done.
|
||||
|
||||
**Bot Meta**
|
||||
Update `Ansibullbot` so it knows who to notify if/when bugs or PRs are raised against your modules
|
||||
`BOTMETA.yml <https://github.com/ansible/ansible/blob/devel/.github/BOTMETA.yml>`_.
|
||||
|
||||
If there are multiple people that can be notified, please list them. That avoids waiting on a single person who may be unavailable for any reason. Note that in `BOTMETA.yml` you can take ownership of an entire directory.
|
||||
|
||||
|
||||
**Review Module web docs**
|
||||
Review the autogenerated module documentation for each of your modules, found in :ref:`Module Docs <modules_by_category>` to ensure they are correctly formatted. If there are any issues please fix by raising a single PR.
|
||||
|
||||
If the module documentation hasn't been published live yet, please let a member of the Ansible Core Team know in the ``#ansible-devel`` IRC channel.
|
||||
|
||||
.. note:: Consider adding a scenario guide to cover how to use your set of modules. Use the :ref:`sample scenario guide rst file <scenario_template>` to help you get started. For network modules, see :ref:`documenting_modules_network` for further documentation requirements.
|
||||
If you need help or advice, consider join the ``#ansible-devel`` IRC channel (see how in the "Where to get support").
|
||||
|
||||
New to git or GitHub
|
||||
====================
|
||||
|
|
@ -146,9 +78,3 @@ We realize this may be your first use of Git or GitHub. The following guides may
|
|||
* `How to create a fork of ansible/ansible <https://help.github.com/articles/fork-a-repo/>`_
|
||||
* `How to sync (update) your fork <https://help.github.com/articles/syncing-a-fork/>`_
|
||||
* `How to create a Pull Request (PR) <https://help.github.com/articles/about-pull-requests/>`_
|
||||
|
||||
Please note that in the Ansible Git Repo the main branch is called ``devel`` rather than ``master``, which is used in the official GitHub documentation
|
||||
|
||||
After your first PR has been merged ensure you "sync your fork" with ``ansible/ansible`` to ensure you've pulled in the directory structure and and shared code or documentation previously created.
|
||||
|
||||
As stated in the GitHub documentation, always use feature branches for your PRs, never commit directly into ``devel``.
|
||||
|
|
|
|||
Loading…
Reference in a new issue