login: Focus the username field on load
[patchwork] / docs / development.md
1 # Developing patchwork
2
3 ## Using virtualenv
4
5 It's a good idea to use virtualenv to develop Python software. Virtual
6 environments are "instances" of your system Python, without any of the
7 additional Python packages installed. They are useful to develop and deploy
8 patchwork against a "well known" set of dependencies, but they can also be
9 used to test patchwork against several versions of Django.
10
11 1. Install pip, virtualenv (python-pip, python-virtualenv packages)
12
13    Because we're going to recompile our dependencies, we'll also need
14    development headers. For the MySQL/MariaDB setups these are
15    `mariadb-devel` (Fedora), `libmysqlclient-dev` (Debian)
16
17 2. Create a new virtual environement.
18
19    Inside a virtual env, we'll just install the dependencies needed for
20    patchwork and run it from there.
21
22        $ virtualenv django-1.8
23
24    This will create a virtual env called 'django-1.8' in eponymous directory.
25
26 3. Activate a virtual environment
27
28        $ source django-1.8/bin/activate
29        (django-1.8)$
30
31    The shell prompt is preprended with the virtual env name.
32
33 4. Install the required dependencies
34
35    To ease this task, it's customary to maintain a list of dependencies in a
36    text file and install them in one go. One can maintain such a list of
37    dependencies per interesting configuration.
38
39        (django-1.8)$ pip install -r docs/requirements-dev.txt
40
41    You will also need to install a version of Django - we don't install this
42    by default to allow development against multiple versions of Django. This
43    can be installed like so (assuming Django 1.8):
44
45        (django-1.8)$ pip install 'django<1.9,>=1.8'
46
47    Of course, this is a one-time step: once installed in the virtual
48    environment there is no need to to install requirements again.
49
50 5. Run the development server
51
52        (django-1.8)$ ./manage.py --version
53        1.8
54        (django-1.8)$ ./manage.py runserver
55
56 Once finished, you can kill the server (`Ctrl` + `C`) and exit the the virtual
57 environment:
58
59     (django-1.8)$ deactivate
60     $
61
62 Should you wish to re-enter this environment, simply source the `activate`
63 script again.
64
65 ## Running Tests
66
67 patchwork includes a [tox] script to automate testing. Before running this, you
68 should probably install tox:
69
70     $ pip install tox
71
72 You can show available
73 targets like so:
74
75     $ tox --list
76
77 You'll see that this includes a number of targets to run unit tests against the
78 different versions of Django supported, along with some other targets related
79 to code coverage and code quality. To run these, use the `-e` parameter:
80
81     $ tox -e py27-django18
82
83 In the case of the unit tests targets, you can also run specific tests by
84 passing the fully qualified test name as an additional argument to this
85 command:
86
87     $ tox -e py27-django18 patchwork.tests.SubjectCleanUpTest
88
89 Because patchwork support multiple versions of Django, it's very important
90 that you test against all supported versions. When run without argument, tox
91 will do this:
92
93     $ tox
94
95 [tox]: https://tox.readthedocs.org/en/latest/