* Suggest ansible ad-hoc command while developing module (#70308) If a local module has no documentation, the doc command will fail without any hints of what is wrong. Add another way to confirm the presence of a local module. * Update docs/docsite/rst/dev_guide/developing_locally.rst Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit82e5d03bdb
) * Update AWS Integration test docmentation (#70454) (cherry picked from commite1ba7dc52a
) * Update hacking/shippable docs. The `--all` option downloads more than is needed for analyzing code coverage. (cherry picked from commitfb7740ae3b
) * Document that subversion module requires subversion (#70537) (cherry picked from commit64c2cb273f
) * update documentation link to python 3 (#70509) update the docs link for strftime on the filters page to point to the python3 docs (cherry picked from commitf7db428375
) * Update windows_winrm.rst (#70306) gcc also needed to be installed alongside python-devel, krb5-devel, krb5-libs, and krb5-workstation. (cherry picked from commitf4ea43c4a0
) * updated requirements file for docs build (#70609) (cherry picked from commit38ccfb4a3e
) * Clarify that index_var is 0 indexed (#70548) A little further down the page is another index, ansible_loop.index, which shares a similar description but is 1 indexed. Its zero indexed twin has a 0 suffix. ``ansible_loop.index`` The current iteration of the loop. (1 indexed) ``ansible_loop.index0`` The current iteration of the loop. (0 indexed) To remove ambiguity around the usage of index_var, explicitly mention that this variable is 0 indexed. (cherry picked from commitc410311f55
) * docs: update module development docs (#70594) Update module development docs for flattened modules directory. Fixes: #70261 (at least partially) Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit20209c508f
) * Doc: fix examples of changelog entries. (#70551) (cherry picked from commitedcd1a1a70
) * Document tags are not supported with task meta. (#70590) fixes #70338 (cherry picked from commit40591d5fbb
) * docs: update date format in removed_at_date (#70597) removed_at_date requires YYYY-MM-DD format. Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit375c6b4ae4
) * partial update of community docs to reflect collections transition (#70488) (cherry picked from commitf1f782fc37
) Co-authored-by: Michael Ritsema <michaelritsema@users.noreply.github.com> Co-authored-by: Mark Chappell <mchappel@redhat.com> Co-authored-by: Matt Clay <matt@mystile.com> Co-authored-by: Alan Rominger <arominge@redhat.com> Co-authored-by: FloMiau <37121807+FloMiau@users.noreply.github.com> Co-authored-by: mahadelmi <mahadelmi@cmail.carleton.ca> Co-authored-by: Sayee <57951841+sayee-jadhav@users.noreply.github.com> Co-authored-by: Karl Goetz <goetzk@users.noreply.github.com> Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com> Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru> Co-authored-by: Baptiste Mille-Mathias <baptiste.millemathias@gmail.com> Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
80 lines
5.2 KiB
ReStructuredText
80 lines
5.2 KiB
ReStructuredText
.. _developing_modules_in_groups:
|
|
|
|
*************************
|
|
Creating a new collection
|
|
*************************
|
|
|
|
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:
|
|
|
|
.. include:: shared_snippets/licensing.txt
|
|
|
|
Before you start coding
|
|
=======================
|
|
|
|
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`.
|
|
* 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 conventions
|
|
==================
|
|
|
|
Fully Qualified Collection Names (FQCNs) for plugins and modules include three elements:
|
|
|
|
* 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``
|
|
|
|
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 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
|
|
====================
|
|
|
|
Ansible has a thriving and knowledgeable community of module developers that is a great resource for getting your questions answered.
|
|
|
|
In the :ref:`ansible_community_guide` you can find how to:
|
|
|
|
* 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>`_
|
|
|
|
Required files
|
|
==============
|
|
|
|
Your collection should include the following files to be usable:
|
|
|
|
* 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*
|
|
|
|
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.
|
|
|
|
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
|
|
====================
|
|
|
|
We realize this may be your first use of Git or GitHub. The following guides may be of use:
|
|
|
|
* `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/>`_
|