On Debian this can be easily done with::

     apt-get install virtualenv virtualenvwrapper git python-pip python-dev \

     libffi-dev libssl-dev

2. In order to be able to run role tests, it is necessary to install `VirtualBox

   <https://www.virtualbox.org/>`_ and `Vagrant <https://www.vagrantup.com/>`_,

   using instructions outlined on their respective websites. It is recommended

   to use latest versions available. At time of this writing the role tests have

   been successfully run on *VirtualBox 5.2.12* and *Vagrant 2.0.4*.

3. In order to allow static IPv6 addresses to be allocated to virtual

   machines during testing, it is necessary to explicitly white-list

   the range used by the tests. Once the configuration file has been

   created, however, even the VirtualBox default allowed IPv4 subnet

   needs to be in the configuration explicitly as well.

   Update the VirtulBox configuration file (and make sure it can be

   read by the user running the tests):

   :file:`/etc/vbox/networks.conf`

   ::

     * 192.168.56.0/21

     * fd00::192:168:56:0/116

4. Clone the git repository::

     git clone https://code.majic.rs/majic-ansible-roles/ ~/projects/

5. Create a separate Python virtual environment::

     mkvirtualenv majic-ansible-roles -a ~/projects/majic-ansible-roles/

6. Make sure the virtual environment has been activated, and install `pip-tools

   <https://github.com/jazzband/pip-tools>`_::

     workon majic-ansible-roles

     pip install pip-tools

7. Synchronise Python virtual environment with requirements file using

   **pip-tools**::

     workon majic-ansible-roles

     pip-sync

   .. note::

   ::

Development conventions

-----------------------

In order to maintain consistency across different roles and documentation, this

section describes development conventions that should be followed while making

modifications.

Task specifications

~~~~~~~~~~~~~~~~~~~

When writing new and updating existing tasks, keep the following in mind:

- Quote sensibly. If specifying paths (for example ``src``, ``dest``, ``path``

  etc in various models), quote the string to make it stand-out better and to

  avoid breakages.

- Avoid usage of ``set_facts`` task when same functionality can be achieved via

  ``defaults/main.yml``.

- When specifying tasks, use the fully expanded form. Do not use single-line

  form with ``param=value``.

- When specifying ``command`` or ``shell`` tasks, in case a ``creates``

  parameter or such need to be used, specify them as part of task's ``args``

  parameter. E.g.::

    - name: Run command

      command: mycommand

      args:

        creates: "/etc/mycommand"

- When sepcifying tasks, keep the following ordering between different task

  parameters:

  - ``name``

  - Module and its parameters.

  - ``become``

  - ``become_user``

  - ``when``

  - ``with_items`` / ``with_dict`` / ``with_nested``

  - ``wait_for``

  - ``register``

  - ``changed_when``

  - ``failed_when``

  - ``no_log``

  - ``notify``

  - Task tags.