diff --git a/docsite/rst/community.rst b/docsite/rst/community.rst index d75ec8d0bb..9448b7d1ea 100644 --- a/docsite/rst/community.rst +++ b/docsite/rst/community.rst @@ -62,11 +62,14 @@ I'd Like To Report A Bugs Ansible practices responsible disclosure - if this is a security related bug, email `security@ansible.com `_ instead of filing a ticket or posting to the Google Group and you will receive a prompt response. -Bugs should be reported to `github.com/ansible/ansible `_ after +Bugs related to the core language should be reported to `github.com/ansible/ansible `_ 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. -When filing a bug, please use the `issue template `_ to provide all relevant information. +MODULE related bugs however should go to `ansible-modules-core `_ or `ansible-modules-extras `_ based on the classification of the module. This is listed on the bottom of the docs page for any module. + +When filing a bug, please use the `issue template `_ to provide all relevant information, regardless of what repo you are filing a ticket against. + 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. @@ -102,8 +105,7 @@ documenting a new feature, submit a github pull request to the code that lives in the “docsite/rst” subdirectory of the project for most pages, and there is an "Edit on GitHub" link up on those. -Module documentation is generated from a DOCUMENTATION structure embedded in the source code of each module -in the library/ directory. +Module documentation is generated from a DOCUMENTATION structure embedded in the source code of each module, which is in either the ansible-modules-core or ansible-modules-extra repos on github, depending on the module. Information about this is always listed on the bottom of the web documentation for each module. Aside from modules, the main docs are in restructured text format. @@ -131,9 +133,9 @@ Contributing Code (Features or Bugfixes) ---------------------------------------- The Ansible project keeps it’s source on github at -`github.com/ansible/ansible `_ - -and takes contributions through +`github.com/ansible/ansible `_ for the core application, and two sub repos ansible/ansible-modules-core and ansible/ansible-modules-extras for module related items. If you need to know if a module is in 'core' or 'extras', consult the web documentation page for that module. + +The project takes contributions through `github pull requests `_. It is usually a good idea to join the ansible-devel list to discuss any large features prior to submission, and this especially helps in avoiding duplicate work or efforts where we decide, upon seeing a pull request for the first time, that revisions are needed. (This is not usually needed for module development, but can be nice for large changes). diff --git a/docsite/rst/developing_modules.rst b/docsite/rst/developing_modules.rst index 0b1695c90f..9fa35f4d3e 100644 --- a/docsite/rst/developing_modules.rst +++ b/docsite/rst/developing_modules.rst @@ -11,9 +11,17 @@ See :doc:`modules` for a list of various ones developed in core. Modules can be written in any language and are found in the path specified by `ANSIBLE_LIBRARY` or the ``--module-path`` command line option. +By default, everything that ships with ansible is pulled from it's source tree, but +additional paths can be added. + +The directory "./library", alongside your top level playbooks, is also automatically +added as a search directory. + Should you develop an interesting Ansible module, consider sending a pull request to the -`github project `_ to see about getting your module -included in the core project. +`moudule-extras project `_. There's also a core +repo for more established and widely used modules. "Extras" modules may be promoted to core periodically, +but there's no fundamental difference in the end - both ship with ansible, all in one package, regardless +of how you acquire ansible. .. _module_dev_tutorial: @@ -59,7 +67,7 @@ Testing Modules There's a useful test script in the source checkout for ansible:: - git clone git@github.com:ansible/ansible.git + git clone git@github.com:ansible/ansible.git --recursive source ansible/hacking/env-setup chmod +x ansible/hacking/test-module @@ -78,6 +86,7 @@ If you did not, you might have a typo in your module, so recheck it and try agai Reading Input ````````````` + Let's modify the module to allow setting the current time. We'll do this by seeing if a key value pair in the form `time=` is passed in to the module. @@ -428,15 +437,33 @@ built and appear in the 'docsite/' directory. .. _module_contribution: -Getting Your Module Into Core -````````````````````````````` +Module Paths +```````````` + +If you are having trouble getting your module "found" by ansible, be sure it is in the ANSIBLE_LIBRARY_PATH. + +If you have a fork of one of the ansible module projects, do something like this:: + + ANSIBLE_LIBRARY=~/ansible-module-core:~/ansible-module-extras + +And this will make the items in your fork be loaded ahead of what ships with Ansible. Just be sure +to make sure you're not reporting bugs on versions from your fork! + +To be safe, if you're working on a variant on something in Ansible's normal distribution, it's not +a bad idea to give it a new name while you are working on it, to be sure you know you're pulling +your version. + +Getting Your Module Into Ansible +```````````````````````````````` High-quality modules with minimal dependencies -can be included in the core, but core modules (just due to the programming +can be included in the ansible, but modules (just due to the programming preferences of the developers) will need to be implemented in Python and use the AnsibleModule common code, and should generally use consistent arguments with the rest of the program. Stop by the mailing list to inquire about requirements if you like, and submit -a github pull request to the main project. +a github pull request to the `extras `_ project. +Included modules will ship with ansible, and also have a change to be promoted to 'core' status, which +gives them slightly higher development priority (though they'll work in exactly the same way). .. seealso:: diff --git a/docsite/rst/developing_test_pr.rst b/docsite/rst/developing_test_pr.rst index b19bf06493..76b0a53eef 100644 --- a/docsite/rst/developing_test_pr.rst +++ b/docsite/rst/developing_test_pr.rst @@ -45,12 +45,16 @@ If you want to run the full integration test suite you'll also need the followin Second, if you haven't already, clone the Ansible source code from GitHub:: - git clone https://github.com/ansible/ansible.git + git clone https://github.com/ansible/ansible.git --recursive cd ansible/ .. note:: If you have previously forked the repository on GitHub, you could also clone it from there. +.. note:: + If updating your repo for testing something module related, use "git rebase origin/devel" and then "git submodule update" to fetch + the latest development versions of modules. Skipping the "git submodule update" step will result in versions that will be stale. + Activating The Source Checkout ++++++++++++++++++++++++++++++ diff --git a/docsite/rst/intro_installation.rst b/docsite/rst/intro_installation.rst index 410284ab7d..a03ccdb0fb 100644 --- a/docsite/rst/intro_installation.rst +++ b/docsite/rst/intro_installation.rst @@ -107,7 +107,7 @@ To install from source. .. code-block:: bash - $ git clone git://github.com/ansible/ansible.git + $ git clone git://github.com/ansible/ansible.git --recursive $ cd ./ansible $ source ./hacking/env-setup @@ -119,6 +119,12 @@ Ansible also uses the following Python modules that need to be installed:: $ sudo pip install paramiko PyYAML jinja2 httplib2 +Note when updating ansible, be sure to not only update the source tree, but also the "submodules" in git +which point at Ansible's own modules (not the same kind of modules, alas). + + $ git pull --rebase + $ git submodule update + Once running the env-setup script you'll be running from checkout and the default inventory file will be /etc/ansible/hosts. You can optionally specify an inventory file (see :doc:`intro_inventory`) other than /etc/ansible/hosts: diff --git a/hacking/module_formatter.py b/hacking/module_formatter.py index c8c077a631..3a6d372631 100755 --- a/hacking/module_formatter.py +++ b/hacking/module_formatter.py @@ -192,6 +192,7 @@ def process_module(module, options, env, template, outputname, module_map): print "rendering: %s" % module + fname = module_map[module] # ignore files with extensions @@ -209,6 +210,13 @@ def process_module(module, options, env, template, outputname, module_map): if doc is None: return "SKIPPED" + if "core" in module: + print "CORE" + doc['core'] = True + else: + doc['core'] = False + + all_keys = [] if not 'version_added' in doc: diff --git a/hacking/templates/rst.j2 b/hacking/templates/rst.j2 index 54fbafefc1..93213f47dd 100644 --- a/hacking/templates/rst.j2 +++ b/hacking/templates/rst.j2 @@ -101,3 +101,31 @@ Examples {% endfor %} {% endif %} +Developers, Testers, and Bug Reporting +-------------------------------------- + +{% set repo = "https://github.com/ansible/ansible-modules-extras" %} +{% set tracker = "https://github.com/ansible/ansible-modules-extras/issues" %} +{% if core %} + {% set repo = "https://github.com/ansible/ansible-modules-core" %} + {% set tracker = "https://github.com/ansible/ansible-modules-core/issues" %} +{% endif %} + +This source of this module is hosted on GitHub in the `{{ repo }} <{{ repo }}>`_ repo. + +If you believe you have found a bug in this module, and are already running the latest stable or development version of Ansbile, first look in the issue tracker at `{{ tracker }} <{{ tracker }}>`_ to see if a bug has already been filed. If not, we would be greatful if you would file one. + +Should you have a question rather than a bug report, inquries are welcome on the `ansible-project google group ` or on Ansible's "#ansible" channel, located on irc.freenode.net. Development oriented topics should instead use the similar `ansible-devel google group `_. + +Documentation updates for this module can also be edited directly by submitting a pull request to the module source code, just look for the "DOCUMENTATION" block in the source tree. + +{% if not core %} + +Note that this module is designated a "extras" module. Non-core modules are still fully usuable, but may recieve slightly lower response rates for issues and pull requests. +Popular "extras" modules may be promoted to core modules over time. + +{% endif %} + +For help in developing on modules, should you be so inclined, please read :doc:`community`, :doc:`developing_test_pr` and :doc:`developing_modules`. + +