1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
Contributing
============
Coding Standards
----------------
**Follow PEP8**. All code is currently PEP8 compliant and it should stay this
way.
Changes that fix semantic issues will be generally be happily received, but
please keep such changes separate from functional changes.
`pep8` targets are provided via tox. Refer to the :ref:`testing` section
below for more information on usage of this tool.
.. _testing:
Testing
-------
Patchwork includes a `tox`_ script to automate testing. This requires a
functional database and some Python requirements like `tox`. Refer to
:doc:`installation` for information on how to configure these.
You may also need to install `tox`. If so, do this now:
.. code-block:: shell
$ sudo pip install tox
.. tip::
If you're using Docker, you may not need to install `tox`
locally. Instead, it will already be installed inside the
container. For Docker, you can run `tox` like so:
.. code-block:: shell
$ docker-compose run web tox [ARGS...]
Assuming these requirements are met, actually testing Patchwork is quite easy
to do. To start, you can show the default targets like so:
.. code-block:: shell
$ tox -l
You'll see that this includes a number of targets to run unit tests against the
different versions of Django supported, along with some other targets related
to code coverage and code quality. To run one of these, use the ``-e``
parameter:
.. code-block:: shell
$ tox -e py27-django18
In the case of the unit tests targets, you can also run specific tests by
passing the fully qualified test name as an additional argument to this
command:
.. code-block:: shell
$ tox -e py27-django18 patchwork.tests.SubjectCleanUpTest
Because Patchwork support multiple versions of Django, it's very important that
you test against all supported versions. When run without argument, tox will do
this:
.. code-block:: shell
$ tox
.. _release-notes:
Release Notes
-------------
Patchwork uses `reno`_ for release note management. To use `reno`, you must
first install it:
.. code-block:: shell
$ sudo pip install reno
Once installed, a new release note can be created using the ``reno new``
command:
.. code-block:: shell
$ reno new <slugified-summary-of-change>
Modify the created file, removing any irrelevant sections, and include the
modified file in your change.
API
---
As discussed in :doc:`releasing`, the API is versioned differently from
Patchwork itself. Should you make changes to the API, you need to ensure these
only affect newer versions of the API. Refer to previous changes in the
``patchwork/api`` directory and to the `Django REST Framework documentation`_
for more information.
.. important::
All API changes should be called out in :ref:`release notes
<release-notes>` using the ``api`` section.
Submitting Changes
------------------
All patches should be sent to the `mailing list`_. When doing so, please abide
by the `QEMU guidelines`_ on contributing or submitting patches. This covers
both the initial submission and any follow up to the patches. In particular,
ensure:
* :ref:`All tests pass <testing>`
* Documentation has been updated with new requirements, new script names etc.
* :ref:`A release note is included <release-notes>`
.. _tox: https://tox.readthedocs.io/en/latest/
.. _reno: https://docs.openstack.org/developer/reno/
.. _mailing list: https://ozlabs.org/mailman/listinfo/patchwork
.. _QEMU guidelines: http://wiki.qemu.org/Contribute/SubmitAPatch
.. _Django REST Framework documentation: http://www.django-rest-framework.org/api-guide/versioning/
|