@ -14,7 +14,7 @@ If you abuse the trust and break components and builds, etc., the trust level fa
Features, High Level Design, and Roadmap
Features, High Level Design, and Roadmap
========================================
========================================
As a core team member, you are an integral part of the team that develops the `roadmap <http://docs.ansible.com/ansible/devel/roadmap/>`_. Please be engaged, and push for the features and fixes that you want to see. Also keep in mind that Red Hat, as a company, will commit to certain features, fixes, APIs, etc. for various releases. Red Hat, the company, and the Ansible team must get these committed features (etc.) completed and released as scheduled. Obligations to users, the community, and customers must come first. Because of these commitments, a feature you want to develop yourself may not get into a release if it impacts a lot of other parts within Ansible.
As a core team member, you are an integral part of the team that develops the :ref:`roadmap <roadmaps>`. Please be engaged, and push for the features and fixes that you want to see. Also keep in mind that Red Hat, as a company, will commit to certain features, fixes, APIs, etc. for various releases. Red Hat, the company, and the Ansible team must get these committed features (etc.) completed and released as scheduled. Obligations to users, the community, and customers must come first. Because of these commitments, a feature you want to develop yourself may not get into a release if it impacts a lot of other parts within Ansible.
Any other new features and changes to high level design should go through the proposal process (TBD), to ensure the community and core team have had a chance to review the idea and approve it. The core team has sole responsibility for merging new features based on proposals.
Any other new features and changes to high level design should go through the proposal process (TBD), to ensure the community and core team have had a chance to review the idea and approve it. The core team has sole responsibility for merging new features based on proposals.
@ -10,7 +10,7 @@ This section discusses how the Ansible development and triage process works.
Road Maps
Road Maps
=========
=========
The Ansible Core team provides a road map for each upcoming release. These road maps can be found `here <http://docs.ansible.com/ansible/devel/roadmap/>`_.
The Ansible Core team provides a road map for each upcoming release. These road maps can be found :ref:`here <roadmaps>`.
.. Roadmaps are User-oriented. We should also list the Roadmap Projects and the Blocker Bug
.. Roadmaps are User-oriented. We should also list the Roadmap Projects and the Blocker Bug
@ -14,7 +14,7 @@ A great way to help the Ansible project is to become a power user:
* Use Ansible everywhere you can
* Use Ansible everywhere you can
* Take tutorials and classes
* Take tutorials and classes
* Read the `official documentation <http://docs.ansible.com/ansible/latest/index.html>`_
* Read the :ref:`official documentation <ansible_documentation>`
* Study some of the `many excellent books <https://www.amazon.com/s/ref=nb_sb_ss_c_2_7?url=search-alias%3Dstripbooks&field-keywords=ansible&sprefix=ansible%2Caps%2C260>`_ about Ansible
* Study some of the `many excellent books <https://www.amazon.com/s/ref=nb_sb_ss_c_2_7?url=search-alias%3Dstripbooks&field-keywords=ansible&sprefix=ansible%2Caps%2C260>`_ about Ansible
@ -22,7 +22,7 @@ See :ref:`all_modules` for a list of existing modules.
Modules can be written in any language and are found in the path specified
Modules can be written in any language and are found in the path specified
by :envvar:`ANSIBLE_LIBRARY` or the ``--module-path`` command line option or
by :envvar:`ANSIBLE_LIBRARY` or the ``--module-path`` command line option or
in the `library section of the Ansible configuration file <http://docs.ansible.com/ansible/intro_configuration.html#library>`_.
in the :envvar:`library section of the Ansible configuration file <ANSIBLE_LIBRARY>`.
.._module_dev_should_you:
.._module_dev_should_you:
@ -49,11 +49,11 @@ If you find an existing PR that looks like it addresses the issue you are trying
Action plugins get run on the master instead of on the target. For modules like file/copy/template, some of the work needs to be done on the master before the module executes on the target. Action plugins execute first on the master and can then execute the normal module on the target if necessary.
Action plugins get run on the master instead of on the target. For modules like file/copy/template, some of the work needs to be done on the master before the module executes on the target. Action plugins execute first on the master and can then execute the normal module on the target if necessary.
For more information about action plugins, `read the action plugins documentation here <https://docs.ansible.com/ansible/dev_guide/developing_plugins.html>`_.
For more information about action plugins, read the :ref:`action plugins documentation <developing_plugins>`.
4. Should you use a role instead?
4. Should you use a role instead?
Check out the roles documentation`available here <http://docs.ansible.com/ansible/playbooks_reuse_roles.html#roles>`_.
Check out the :ref:`roles documentation<playbooks_reuse_roles>`.
5. Should you write multiple modules instead of one module?
5. Should you write multiple modules instead of one module?
@ -33,7 +33,7 @@ The following checklist items are important guidelines for people who want to c
'supported_by': 'community',
'supported_by': 'community',
'metadata_version': '1.1'}
'metadata_version': '1.1'}
The complete module metadata specification is here: `Ansible metadata block <https://docs.ansible.com/ansible/dev_guide/developing_modules_documenting.html#ansible-metadata-block>`_
Read the complete :ref:`module metadata specification <ansible-metadata-block>` for more information.
* Documentation: Make sure it exists
* Documentation: Make sure it exists
* Module documentation should briefly and accurately define what each module and option does, and how it works with others in the underlying system. Documentation should be written for broad audience--readable both by experts and non-experts. This documentation is not meant to teach a total novice, but it also should not be reserved for the Illuminati (hard balance).
* Module documentation should briefly and accurately define what each module and option does, and how it works with others in the underlying system. Documentation should be written for broad audience--readable both by experts and non-experts. This documentation is not meant to teach a total novice, but it also should not be reserved for the Illuminati (hard balance).
@ -129,7 +129,7 @@ If there are multiple people that can be notified, please list them. That avoids
**Review Module web docs**
**Review Module web docs**
Review the autogenerated module documentation for each of your modules, found in `Module Docs <http://docs.ansible.com/ansible/modules_by_category.html>`_ to ensure they are correctly formatted. If there are any issues please fix by raising a single PR.
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.
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.
@ -279,7 +279,7 @@ The following is an example of how this lookup is called::
For more example lookup plugins, check out the source code for the lookup plugins that are included with Ansible here: `lib/ansible/plugins/lookup <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/lookup>`_.
For more example lookup plugins, check out the source code for the lookup plugins that are included with Ansible here: `lib/ansible/plugins/lookup <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/lookup>`_.
For more usage examples of lookup plugins, see `Using Lookups <http://docs.ansible.com/ansible/playbooks_lookups.html>`_.
For more usage examples of lookup plugins, see :ref:`Using Lookups<playbooks_lookups>`.
Ansible modules normally return a data structure that can be registered into a variable, or seen directly when output by
Ansible modules normally return a data structure that can be registered into a variable, or seen directly when output by
the `ansible` program. Each module can optionally document its own unique return values (visible through ansible-doc and https://docs.ansible.com).
the `ansible` program. Each module can optionally document its own unique return values (visible through ansible-doc and on the :ref:`main docsite<ansible_documentation>`.
This document covers return values common to all modules.
This document covers return values common to all modules.
@ -65,7 +65,7 @@ For instance ensuring that a specific tenant exists, is done using the following
description: Customer XYZ
description: Customer XYZ
state: present
state: present
A complete list of existing ACI modules is available for `the latest stable release <http://docs.ansible.com/ansible/latest/modules/list_of_network_modules.html#aci>`_ as well as `the current development version <http://docs.ansible.com/ansible/devel/modules/list_of_network_modules.html#aci>`_.
A complete list of existing ACI modules is available for the latest stable release on the :ref:`list of network modules <list_of_network_modules>`. You can also view the `current development version <http://docs.ansible.com/ansible/devel/modules/list_of_network_modules.html#aci>`_.
@ -238,7 +238,7 @@ virtual network already with an existing subnet, you can run the following to cr
Dynamic Inventory Script
Dynamic Inventory Script
------------------------
------------------------
If you are not familiar with Ansible's dynamic inventory scripts, check out `Intro to Dynamic Inventory <http://docs.ansible.com/ansible/intro_dynamic_inventory.html>`_.
If you are not familiar with Ansible's dynamic inventory scripts, check out :ref:`Intro to Dynamic Inventory <intro_dynamic_inventory>`.
The Azure Resource Manager inventory script is called azure_rm.py. It authenticates with the Azure API exactly the same as the
The Azure Resource Manager inventory script is called azure_rm.py. It authenticates with the Azure API exactly the same as the
Azure modules, which means you will either define the same environment variables described above in `Using Environment Variables`_,
Azure modules, which means you will either define the same environment variables described above in `Using Environment Variables`_,
- packet_sshkey: adds a public SSH key from file or value to the Packet infrastructure. Every subsequently-created device will have this public key installed in .ssh/authorized_keys.
- packet_sshkey: adds a public SSH key from file or value to the Packet infrastructure. Every subsequently-created device will have this public key installed in .ssh/authorized_keys.
- packet_device: manages servers on Packet. You can use this module to create, restart and delete devices.
- packet_device: manages servers on Packet. You can use this module to create, restart and delete devices.
Note, this guide assumes you are familiar with Ansible and how it works. If you're not, have a look at their `docs <http://docs.ansible.com/>`_ before getting started.
Note, this guide assumes you are familiar with Ansible and how it works. If you're not, have a look at their :ref:`docs <ansible_documentation>` before getting started.
Ansible executes commands through WinRM. These processes are different from
Ansible executes commands through WinRM. These processes are different from
@ -110,7 +112,7 @@ See :doc:`become` more info on how to use become. The limitations section at
This program won't install with Ansible
This program won't install with Ansible
```````````````````````````````````````
```````````````````````````````````````
See `the question <http://docs.ansible.com/ansible/latest/windows_faq.html#i-can-run-this-command-locally-but-it-does-not-work-under-ansible>`_ for more information about WinRM limitations.
See :ref:`this question <windows_faq_winrm>` for more information about WinRM limitations.
What modules are available?
What modules are available?
```````````````````````````
```````````````````````````
@ -119,8 +121,8 @@ Linux/Unix machines and arbitrary web services. These modules are written in
Python and most of them do not work on Windows.
Python and most of them do not work on Windows.
Because of this, there are dedicated Windows modules that are written in
Because of this, there are dedicated Windows modules that are written in
PowerShell and are meant to be run on Windows hosts. A list of this modules
PowerShell and are meant to be run on Windows hosts. A list of these modules
can be found `here <http://docs.ansible.com/list_of_windows_modules.html>`_.
can be found :ref:`here <list_of_windows_modules>`.
In addition, the following Ansible Core modules/action-plugins work with Windows:
In addition, the following Ansible Core modules/action-plugins work with Windows:
Alicia Cozine
7 years ago
committed by