************
Hacking MaaS
************


Coding style
============

MaaS follows the `Launchpad Python Style Guide`_, except where it gets
Launchpad specific, and where it talks about `method naming`_. MaaS
instead adopts `PEP-8`_ naming in all cases, so method names should
usually use the ``lowercase_with_underscores`` form.

.. _Launchpad Python Style Guide:
  https://dev.launchpad.net/PythonStyleGuide

.. _method naming:
  https://dev.launchpad.net/PythonStyleGuide#Naming

.. _PEP-8:
  http://www.python.org/dev/peps/pep-0008/


Prerequisites
=============
You will need to manually install Postgres 9.1 (postgresql-9.1 and
libpq-dev), RabbitMQ (rabbitmq-server), python-dev and make::

    $ sudo apt-get install postgresql-9.1 libpq-dev rabbitmq-server python-dev make

Also, you might want to install Bazaar (bzr) to grab the source code directly
from Launchpad::

    $ sudo apt-get install bzr

All other development dependencies are pulled automatically from `PyPI`_
when buildout runs.

.. _PyPI:
  http://pypi.python.org/


Getting the latest version of the code
======================================

You can grab the code manually from Launchpad but Bazaar makes it easy to fetch
the last version of the code. Go into the directory where you want the code
to reside and run::

    $ bzr branch lp:maas maas && cd maas

Development MaaS server setup
=============================

Access to the database is configured in ``src/maas/development.py``.

The ``Makefile`` or the test suite sets up a development database
cluster inside your branch. It lives in the ``db`` directory, which
gets created on demand. You'll want to shut it down before deleting a
branch; see below.

First, set up the project. This fetches all the required dependencies
and sets up some useful commands in ``bin/``::

    $ make

Create the database cluster and initialize the development database::

    $ make syncdb

Optionally, populate your database with the sample data::

    $ make sampledata

Run the development webserver::

    $ make run

Point your browser to http://localhost:8000/

If you've populated your instance with the sample data, you can login as a
simple user using the test account (username: 'test', password: 'test') or the
admin account (username: 'admin', password: 'test').

To shut down the database cluster and clean up all other generated files in
your branch::

    $ make distclean


Adding new source files
=======================

When creating a new source file, a Python module or test for example,
always start with the appropriate template from the ``templates``
directory.


Documentation
=============

Use `reST`_ with the `convention for headings as used in the Python
documentation`_.

.. _reST: http://sphinx.pocoo.org/rest.html

.. _convention for headings as used in the Python documentation:
  http://sphinx.pocoo.org/rest.html#sections