~allenap/maas/docs-and-man-bug-975454

26.1.4 by Gavin Panella
Use the Python documentation's heading convention.
1
************
26.1.1 by Gavin Panella
Document the coding standards other hacking information.
2
Hacking MaaS
26.1.4 by Gavin Panella
Use the Python documentation's heading convention.
3
************
26.1.1 by Gavin Panella
Document the coding standards other hacking information.
4
5
6
Coding style
7
============
8
9
MaaS follows the `Launchpad Python Style Guide`_, except where it gets
10
Launchpad specific, and where it talks about `method naming`_. MaaS
11
instead adopts `PEP-8`_ naming in all cases, so method names should
12
usually use the ``lowercase_with_underscores`` form.
13
14
.. _Launchpad Python Style Guide:
15
  https://dev.launchpad.net/PythonStyleGuide
16
17
.. _method naming:
18
  https://dev.launchpad.net/PythonStyleGuide#Naming
19
20
.. _PEP-8:
21
  http://www.python.org/dev/peps/pep-0008/
22
23
59.1.2 by Julian Edwards
add mention of dev packages of python and postgres
24
Prerequisites
25
=============
171.4.11 by Francis J. Lacoste
Remove duplicate packages.
26
27
You will need to manually install Postgres 9.1, RabbitMQ, python-dev and make::
171.4.9 by Francis J. Lacoste
Remerge changes to load from site-packages.
28
29
    $ sudo apt-get install postgresql-9.1 rabbitmq-server python-dev make
171.4.1 by Francis J. Lacoste
Get all runtime dependencies from site-packages, specify all versions, integrate buildout-versions for easier version management.
30
98.2.2 by Raphael Badin
Update doc.
31
Also, you might want to install Bazaar (bzr) to grab the source code directly
32
from Launchpad::
98.2.1 by Raphael Badin
Update HACKING.txt.
33
34
    $ sudo apt-get install bzr
59.1.1 by Julian Edwards
Mention postgres and rabbit in HACKING.txt
35
171.4.9 by Francis J. Lacoste
Remerge changes to load from site-packages.
36
This is the list of runtime dependencies that you'll need to install::
37
38
    $ sudo apt-get install python-django python-django-piston \
39
        python-django-south python-twisted python-txamqp python-amqplib \
40
        python-formencode python-oauth python-oops python-oops-datedir-repo \
171.4.12 by Francis J. Lacoste
Add missing runtime deps package to HACKING.txt
41
        python-twisted python-oops-wsgi python-oops-twisted \
42
        python-psycopg2 python-yaml
171.4.9 by Francis J. Lacoste
Remerge changes to load from site-packages.
43
44
Additionally, you need to install the following python libraries
45
for development convenience::
46
47
    $ sudo apt-get install python-sphinx python-lxml
48
49
If you intend to run the test suite, you also need xvfb and firefox::
50
51
    $ sudo apt-get install xvfb firefox
168.2.2 by Raphael Badin
Add note in HACKING.txt.
52
59.1.2 by Julian Edwards
add mention of dev packages of python and postgres
53
All other development dependencies are pulled automatically from `PyPI`_
59.1.1 by Julian Edwards
Mention postgres and rabbit in HACKING.txt
54
when buildout runs.
55
59.1.2 by Julian Edwards
add mention of dev packages of python and postgres
56
.. _PyPI:
57
  http://pypi.python.org/
58
59.1.1 by Julian Edwards
Mention postgres and rabbit in HACKING.txt
59
190.2.1 by Gavin Panella
Docs for first-time buildout users.
60
First time using buildout?
61
==========================
62
63
Buildout is used to develop MaaS. Buildout, if configured so, can
64
cache downloaded files and built eggs. If you've not already done
65
something similar, the following snippet will massively improve build
66
times::
67
68
    [buildout]
69
    download-cache = /home/<your-user-name>/.buildout/cache
70
    eggs-directory = /home/<your-user-name>/.buildout/eggs
71
190.2.3 by Gavin Panella
The cache directory needs to be made by hand.
72
Put this in ``~/.buildout/default.cfg`` and create the ``cache``
73
directory::
74
75
    $ mkdir /home/<your-user-name>/.buildout/cache
76
77
The ``eggs`` directory will be created automatically.
190.2.1 by Gavin Panella
Docs for first-time buildout users.
78
79
98.2.3 by Raphael Badin
Typo.
80
Getting the latest version of the code
98.2.4 by Raphael Badin
Typo.
81
======================================
98.2.1 by Raphael Badin
Update HACKING.txt.
82
83
You can grab the code manually from Launchpad but Bazaar makes it easy to fetch
84
the last version of the code. Go into the directory where you want the code
85
to reside and run::
86
87
    $ bzr branch lp:maas maas && cd maas
88
190.2.2 by Gavin Panella
Tidy.
89
26.1.1 by Gavin Panella
Document the coding standards other hacking information.
90
Development MaaS server setup
91
=============================
92
93
Access to the database is configured in ``src/maas/development.py``.
94
95
The ``Makefile`` or the test suite sets up a development database
96
cluster inside your branch. It lives in the ``db`` directory, which
97
gets created on demand. You'll want to shut it down before deleting a
98
branch; see below.
99
26.1.5 by Gavin Panella
Just running make does not create the database cluster.
100
First, set up the project. This fetches all the required dependencies
101
and sets up some useful commands in ``bin/``::
26.1.1 by Gavin Panella
Document the coding standards other hacking information.
102
103
    $ make
104
26.1.5 by Gavin Panella
Just running make does not create the database cluster.
105
Create the database cluster and initialize the development database::
26.1.1 by Gavin Panella
Document the coding standards other hacking information.
106
107
    $ make syncdb
108
104.2.1 by Raphael Badin
Fix doc.
109
Optionally, populate your database with the sample data::
110
111
    $ make sampledata
112
162.2.1 by Gavin Panella
Update Cobbler installation instructions.
113
Install Cobbler, and import at least one distro and profile::
130.3.15 by Gavin Panella
Explain that Cobbler must be installed.
114
162.2.1 by Gavin Panella
Update Cobbler installation instructions.
115
    $ sudo apt-get install apache2 cobbler
116
    $ sudo cobbler-ubuntu-import precise-i386  # For example.
130.3.15 by Gavin Panella
Explain that Cobbler must be installed.
117
130.3.12 by Gavin Panella
Add instructions about adding $USER to Cobbler's user list.
118
Add yourself as a user in Cobbler. For convenience, give yourself the
119
password ``test``::
120
121
    $ sudo htdigest /etc/cobbler/users.digest Cobbler $USER
122
162.2.2 by Gavin Panella
Explain how to use the fake Provisioning Server.
123
Alternatively, if you're not interested in the Provisioning Server or
124
Cobbler, set ``PSERV_URL`` to ``None`` in one of ``maas``'s settings
125
files (typically ``src/maas/demo.py``), and a fake Provisioning Server
126
will be used instead.
127
26.1.1 by Gavin Panella
Document the coding standards other hacking information.
128
Run the development webserver::
129
130
    $ make run
131
132
Point your browser to http://localhost:8000/
133
32.5.2 by Raphael Badin
Add doc.
134
If you've populated your instance with the sample data, you can login as a
135
simple user using the test account (username: 'test', password: 'test') or the
49.1.1 by Raphael Badin
Put the right pw in the docs.
136
admin account (username: 'admin', password: 'test').
32.5.2 by Raphael Badin
Add doc.
137
26.1.1 by Gavin Panella
Document the coding standards other hacking information.
138
To shut down the database cluster and clean up all other generated files in
139
your branch::
140
141
    $ make distclean
26.1.2 by Gavin Panella
Add a note about using templates.
142
171.4.9 by Francis J. Lacoste
Remerge changes to load from site-packages.
143
Adding new dependencies
144
=======================
145
146
Since MaaS is distributed mainly as Ubuntu package, all runtime dependencies
147
should be packaged and we should develop with the packaged version if
148
possible. You'll need to add the dependency to the
149
``allowed-eggs-from-site-packages`` option in the ``buildout.cfg`` file. You
150
also need to add it to setup.py (And don't forget to add the version to
151
``versions.cfg`` as we run with ``allowed-picked-version`` set to false.)
152
153
If it is a development-only dependency (i.e. only needed for the test suite, or
154
for developers' convenience), simply running ``buildout`` like this will make
155
the necessary updates to ``versions.cfg``::
156
157
    $ ./bin/buildout -v buildout:allow-picked-versions=true
158
190.2.2 by Gavin Panella
Tidy.
159
26.1.2 by Gavin Panella
Add a note about using templates.
160
Adding new source files
161
=======================
162
163
When creating a new source file, a Python module or test for example,
164
always start with the appropriate template from the ``templates``
165
directory.
26.1.3 by Gavin Panella
Add notes on documentation.
166
167
168
Documentation
169
=============
170
171
Use `reST`_ with the `convention for headings as used in the Python
172
documentation`_.
173
174
.. _reST: http://sphinx.pocoo.org/rest.html
175
176
.. _convention for headings as used in the Python documentation:
177
  http://sphinx.pocoo.org/rest.html#sections
171.4.9 by Francis J. Lacoste
Remerge changes to load from site-packages.
178