internet/community.general
3
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2026-05-06 21:32:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

rewrite of the developer guide, part 1 (#45179)

Browse Source 
* rewrite of the developer guide, part 1
This commit is contained in:
Alicia Cozine
2018-09-07 08:57:36 -05:00
committed by GitHub
parent 1325ddbb0b
commit 9a76441c02
39 changed files with 1231 additions and 2882 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
docs/docsite/rst/dev_guide/developing_modules_in_groups.rst
View File

@@ -1,27 +1,31 @@
.. _developing_modules_in_groups:
*********************************************
Information for submitting a group of modules
=============================================
*********************************************
.. contents:: Topics
: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 best practices that the Ansible core team and community have accumulated.
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.
* Read though all the pages linked off :doc:`developing_modules`; paying particular focus to the :doc:`developing_modules_checklist`.
* For new modules going into Ansible 2.4 we are raising the bar so they must be PEP 8 compliant. See :doc:`testing_pep8` for more information.
* Starting with Ansible version 2.4, all new modules must support Python 2.6 and Python 3.5+. If this is an issue, please contact us (see the "Speak to us" section later in this document to learn how).
* All modules shipped with Ansible must be done so under the GPLv3 license. Files under the ``lib/ansible/module_utils/`` directory should be done so under the BSD license.
* New modules must be PEP 8 compliant. See :doc:`testing_pep8` for more information.
* Starting with Ansible version 2.7, all new modules must :ref:`support Python 2.7+ 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/utils/module_docs_fragments/``.
@@ -30,8 +34,8 @@ Although it's tempting to get straight into coding, there are a few things to be
* Starting with Ansible 2.4 all :ref:`network_modules` MUST have unit tests.
Naming Convention
`````````````````
Naming convention
=================
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`.
@@ -47,7 +51,7 @@ Each module should have the above (or similar) prefix; see existing :ref:`all_mo
Speak to us
```````````
===========
Circulating your ideas before coding is a good way to help you set off in the right direction.
@@ -57,7 +61,7 @@ We've found that writing a list of your proposed module names and a one or two l
Where to get support
````````````````````
====================
Ansible has a thriving and knowledgeable community of module developers that is a great resource for getting your questions answered.
@@ -68,8 +72,8 @@ In the :ref:`ansible_community_guide` you can find how to:
* 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
````````````````````````
Your first pull request
=======================
Now that you've reviewed this document, you should be ready to open your first pull request.
@@ -102,7 +106,7 @@ We have a ``ansibullbot`` helper that comments on GitHub Issues and PRs which sh
Subsequent PRs
``````````````
==============
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.
@@ -116,10 +120,10 @@ Over the years we've experimented with different sized module PRs, ranging from
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.
Finally
```````
Maintaining your modules
========================
Now that your modules are integrated there are a few bits of housekeeping to be done
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
@@ -134,10 +138,10 @@ Review the autogenerated module documentation for each of your modules, found in
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.
New to Git or GitHub
````````````````````
New to git or GitHub
====================
We realise this may be your first use of Git or GitHub. The following guides may be of use:
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/>`_
@@ -147,4 +151,4 @@ Please note that in the Ansible Git Repo the main branch is called ``devel`` rat
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`.
As stated in the GitHub documentation, always use feature branches for your PRs, never commit directly into ``devel``.