== Purpose ==

Ansible has a lot of documentation and is increasingly building out development docs, but not everyone learns the same way. This page provides self-guided labs which are intended to teach new Ansible developers the ins and outs of writing code and working with the github PR process and shippable CI system. It is expected that the developer does a commit+push and waits for tests to run after each step in the process to learn the behavior of shippable tests and ansibot. You are expected to see a lot of errors and failures through this process. Please use the docs, the sourcecode, the community and the Ansible core team (in that order) if you find yourself stuck at any point.

NOTE: Between each step of the pullrequest process, you may need to wait 10-15 minutes for the bot to notice new changes and apply new labels. Shippable is often overloaded as well, so tests may take 30-40 minutes to run.

NOTE: This is not in the official docs because it was rejected. https://github.com/ansible/ansible/pull/26921

== Level 1: module development ==
=== hello world ===
# fork ansible
# checkout the fork
# create a feature branch named FILAMENT_MODULE
# create a new module file lib/ansible/modules/system/filament.py
# put "hello = world" in filament.py
# git add and commit the new file
# push the commit to the feature branch
# open the branch on github.com and send it as a pullrequest to ansible/ansible
# wait for ansibot to triage the issue and for shippable to run the tests
# read the shippable test logs to learn how to run the tests locally
# fix all test failures locally
# commit and push your changes 

=== debugging modules ===

# set a variable named "foo" in the module
# use the python-q library to have the module log the value of "foo"
# set a breakpoint in the module with pdb/epdb
# run the module with test-module
#* get to the breakpoint
#* print "foo"
# run the module with ansible-playbook
#* get to the breakpoint
#* print "foo"
# commit and push the module with the breakpoint added to see CI test failures.
# remove the breakpoint and then commit and push again.

=== integration testing ===

# Create, commit and push an empty file named test/integration/targets/filament/tasks/main.yml
# Make sure the test is being run in shippable.
# Observe the test failures and re-run the test locally with ansible-test.
# Fill in main.yml with 2 tasks
#* call the filament module and register the result
#* assert that the result contains a key "foo" with a value of "bar"
# Fix the module so that the test passes by running the test locally with ansible-test.
# Commit and push your changes.

=== unit testing ===

# add a new function to the module that adds two integeters
# write a unit test to assert that the function returns the correct value for ints/strings/bools

=== module_util ===

# echo "hello world" > lib/ansible/module_utils/filament_utils.py
# make the filament module import the function "foobar" from filament_utils
# fix any shippable errors

=== action plugins ===

# make an action plugin that changes "bar" to "!bar"

== Level 2: lookups ==

# create a new feature branch on your fork
# make a lookup that queries the process table and gets the pid for a process based on an input string
# make a pullrequest from the branch
# write a unit test for that lookup
# write an integration test for the lookup

== Level 3: callbacks ==

# create a new feature branch
# create a new empty file lib/ansible/plugins/callback/filament.py
# create an ansible.cfg that enables and switches the default callback to "filament"
# run a simple playbook
# fix any errors until the ansible-playbook output is readable by referencing the other callbacks

== Level 4: connection plugins ==

# create a new feature branch
# create an empty file lib/ansible/plugins/connection/filament.py
# create a playbook that uses the "filament" connection plugin to run the shell module with "whoami"
# run the playbook
# fix whatever errors you see by referencing the other connection plugins

== Level 5: strategy plugin ==

# subclass the linear strategy in a new strategy called "filament"
# put a 1 second sleep between each task

== Appendix ==

=== Ansible Tools ===

* https://github.com/jctanner/ansible-tools
* https://www.youtube.com/watch?v=miMEYmDT5Iw

==== setup ====
# vagrant init fedora/26-cloud-base
# vagrant up
# vagrant ssh
# sudo dnf -y install git ansible vim-enhanced
# sudo rpm -e --nodeps ansible
# sudo chmod 777 /opt
# git clone https://github.com/jctanner/ansible-tools /opt/ansible-tools
# export PATH=$PATH:/opt/ansible-tools
# sudo mkdir -p /var/cache/ansible
# sudo chmod -R 777 /var/cache/ansible

==== first steps ====

* ansible-list-versions
* ansible-checkout-versions -v
* ansible-workon AP 0000
* cd ~/workspace/issues/AP-0000
# ansible-test-version devel test.sh
# ansible-test-versions --start=1.9 test.sh

=== resources ===
* https://github.com/turkenh/ansible-interactive-tutorial/blob/master/README.md
* https://github.com/jimi-c/ansible/blob/developer_docs/docs/docsite/rst/dev_guide/architecture_deep_dive.rst
* http://docs.ansible.com/ansible/dev_guide/developing_plugins.html
* http://docs.ansible.com/ansible/dev_guide/developing_modules_general.html
* https://docs.ansible.com/ansible/dev_guide/developing_modules_best_practices.html#debugging-ansiblemodule-based-modules
* https://pypi.python.org/pypi/rpdb/
* https://github.com/tstringer/ansible-dev-by-example
* https://pypi.python.org/pypi/epdb
* http://willthames.github.io/2017/07/17/so-you-want-to-test-aws-modules-for-ansible.html
* [https://docs.google.com/presentation/d/10O2Dz10IC84xrA7V0r6TIVm1vdySHY58bm-aFipedi8/edit#slide=id.g1cd90de61f_0_0 ansible internals]

[[Category:Ansible]]