docs: Add a contributors guide

This guide details the steps one should follow to submit patches for
patchwork. It's nothing onerous but rather common sense. This requires
moving the testing section from the development guide to this new
document.

Signed-off-by: Stephen Finucane <stephen.finucane@intel.com>

diff --git a/docs/contributing.md b/docs/contributing.md
new file mode 100644 (file)
index 0000000..1e61b7f
--- /dev/null
+++ b/docs/contributing.md
@@ -0,0 +1,59 @@
+# Tips and Tricks
+
+## 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 seperate from functional changes.
+
+`pep8` targets are provided via tox. Refer to the [testing section](#testing)
+below for more information on usage of this tool.
+
+## Testing
+
+patchwork includes a [tox][ref-tox] script to automate testing. This requires
+a functional database and some Python requirements like `tox`. Please refer
+to the [development guide][doc-development] for information on how to configure
+these.
+
+Assuming these requirements are met, actually testing patchwork is quite easy
+to do. To start, you can show the default targets like so:
+
+    $ tox --list
+
+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:
+
+    $ 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:
+
+    $ 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:
+
+    $ tox
+
+## Submitting Changes
+
+All patches should be sent to the [mailing list][pw-ml]. When doing so, please
+abide by the [QEMU guidelines][ref-qemu-contrib] on contributing or submitting
+patches. This covers both the initial submission and any follow up to the
+patches. In particulat, please ensure:
+
+* [All tests pass](#testing)
+* Documentation has been updated with new requirements, new script names etc.
+* The `CHANGES` file has been updated with any added or removed features
+
+[doc-development]: development.md
+[pw-ml]: https://ozlabs.org/mailman/listinfo/patchwork
+[ref-qemu-contrib]: http://wiki.qemu.org/Contribute/SubmitAPatch
+[ref-tox]: https://tox.readthedocs.org/en/latest/

diff --git a/docs/development.md b/docs/development.md
index 07e0ca07978d7726f96d947223f87ae1cc6b0d3f..3868adf24bdd5aea85a9e499d2d6105e45716161 100644 (file)
--- a/docs/development.md
+++ b/docs/development.md
@@ -90,35 +90,3 @@ The following environmental variables are available to configure settings:
   <dt>PW_TEST_DB_TYPE = 'mysql'</dt>
   <dd>Type of database to use. Options: 'mysql', 'postgresql'</dd>
 </dl>
-
-## Running Tests
-
-patchwork includes a [tox] script to automate testing. Before running this, you
-should probably install tox:
-
-    $ pip install tox
-
-You can show available
-targets like so:
-
-    $ tox --list
-
-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 these, use the `-e` parameter:
-
-    $ 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:
-
-    $ tox -e py27-django18 patchwork.tests.SubjectCleanUpTest
-
-Because patchwork supports multiple versions of Django, it's very important
-that you test against all supported versions. When run without argument, tox
-will do this:
-
-    $ tox
-
-[tox]: https://tox.readthedocs.org/en/latest/

diff --git a/mkdocs.yml b/mkdocs.yml
index 876ebf75efc2aa7f6ccbbcf57be363393b8c68f6..6e28dfe5eed4fd6376689b7dc96833fedce24828 100644 (file)
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -8,3 +8,4 @@ pages:
  - Home: 'index.md'
  - Installation: 'installation.md'
  - Development: 'development.md'
+ - Contributing: 'contributing.md'