Developing UTAH
==============

Provisionioning
---------------

Within the UTAH code, provisioning machines is handled by subclasses of the
:py:class:`.Machine` class.

Scripts should provision machines by creating an instance of a subclass of the
:py:class:`.Inventory` class, and using the :py:meth:`.Inventory.request`
method to obtain a machine. Inventories are intended to prevent resource
collision.

End users not writing scripts can provision machines automatically using
scripts provided by the UTAH package. Please see the main UTAH page for that.

How to use custom preseeds
--------------------------

By default UTAH uses a preseed stored as ``/etc/utah/default-preseed.cfg`` for
the provisioning of the test machine. By giving a **-p preseed_file** input to
UTAH a custom provisioning could be carried out.

For example, the following command would provision the test machine with
quantal server image with the options given in the contents of *preseed_file*
and run the post installation tests given in *master.run*::

    sudo -i -u utah /usr/share/utah/examples/run_utah_tests.py \
        -i http://cdimage.ubuntu.com/ubuntu-server/daily/current/quantal-server-i386.iso \
        -p /absolute_path_to/preseed-file /absolute_path_to/master.run

An example preseed for precise is given in the `Ubuntu Installation Guide
<https://help.ubuntu.com/12.04/installation-guide/example-preseed.txt>`__.

Coding guidelines for developers
--------------------------------

Introduction
~~~~~~~~~~~~

As UTAH codebase becomes more stable, there's an effort to make it not only
work correctly, but also look correctly. To do that, we're using flake8_, a
`static code analysis`_ tool that is a combination of both pyflakes_ and pep8_.
This way, both syntax and PEP008_ errors can be checked in a single shot.

What is PEP8?
~~~~~~~~~~~~~

PEP008_ (Python Enhancement Proposal 8) is a document that contains a set of
style guidelines for developers written by `Guido van Rossum`_ and `Barry
Warsaw`_. It's commonly accepted as the de facto style document for python
developers; so, unless we don't find useful after some time, we decided to
adopt it.

Are there any other guidelines?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Aside from PEP008_, the `Google Python Style Guide`_ has received some
attention as well. Since it differs from PEP008_ at some places, this one isn't
being followed at this time, but some part of it could be used in the future.

Are there any other tools?
~~~~~~~~~~~~~~~~~~~~~~~~~~

Another tool that has a very good reputation is pylint_. While it's a very
useful tool, it's a little bit more difficult to use and requires some time to
configure it to adapt to the policy of a given project. Anyway, it could be
used in the future as well to catch some of the errors/warnings that might not
be detected by flake8_.

.. _Guido van Rossum: https://en.wikipedia.org/wiki/Guido_van_Rossum
.. _Barry Warsaw: http://barry.warsaw.us/
.. _static code analysis: https://en.wikipedia.org/wiki/Static_program_analysis
.. _PEP008: http://www.python.org/dev/peps/pep-0008/
.. _pep8: http://pypi.python.org/pypi/pep8
.. _pyflakes: http://pypi.python.org/pypi/pyflakes
.. _flake8: http://pypi.python.org/pypi/flake8/
.. _Google Python Style Guide:
   http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
.. _pylint: http://pypi.python.org/pypi/pylint/