git.ozlabs.org Git - patchwork/blob - 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/