From: Stephen Finucane Date: Sat, 29 Apr 2017 00:32:23 +0000 (+0100) Subject: docs: Misc fixes X-Git-Tag: v2.0.0-rc1~11 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=97b6a857181ac776011e704d9c81b1d4a27f2573;p=thirdparty%2Fpatchwork.git docs: Misc fixes Add release note requirement to contributing and fix some issues with the development installation guide. Signed-off-by: Stephen Finucane --- diff --git a/docs/development/contributing.rst b/docs/development/contributing.rst index ec38f2d3..0cab79e5 100644 --- a/docs/development/contributing.rst +++ b/docs/development/contributing.rst @@ -18,10 +18,28 @@ below for more information on usage of this tool. Testing ------- -Patchwork includes a `tox`__ script to automate testing. This requires a -functional database and some Python requirements like `tox`. Refer to the +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 or Vagrant-based installs, you may not need to + install `tox` locally. Instead, it will already be installed inside the + container/VM. For Docker, you can run `tox` like so: + + .. code-block:: shell + + $ docker-compose run web tox [ARGS...] + + For Vagrant, SSH into the container and run `tox` as below. + Assuming these requirements are met, actually testing Patchwork is quite easy to do. To start, you can show the default targets like so: @@ -31,7 +49,8 @@ to do. To start, you can show the default targets like so: 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: +to code coverage and code quality. To run one of these, use the ``-e`` +parameter: .. code-block:: shell @@ -53,13 +72,33 @@ this: $ tox -__ https://tox.readthedocs.io/en/latest/ +.. _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 tox + +Once installed, a new release note can be created using the ``reno new`` +command: + +.. code-block:: shell + + $ reno new + +Modify the created file, removing any irrelevant sections, and include the +modified file in your change. 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 +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: @@ -67,7 +106,9 @@ ensure: * Documentation has been updated with new requirements, new script names etc. -* The `CHANGES` file has been updated with any added or removed features +* :ref:`A release note is included ` -__ https://ozlabs.org/mailman/listinfo/patchwork -__ http://wiki.qemu.org/Contribute/SubmitAPatch +.. _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 diff --git a/docs/development/installation.rst b/docs/development/installation.rst index c8049af2..d73bb8b5 100644 --- a/docs/development/installation.rst +++ b/docs/development/installation.rst @@ -3,8 +3,8 @@ Installation This document describes the necessary steps to configure Patchwork in a development environment. If you are interested in deploying Patchwork in a -production environment, please refer to [the deployment guide][doc-deployment] -instead. +production environment, refer to `the deployment guide +<../deployment/installation>`__ instead. To begin, you should clone Patchwork: @@ -19,7 +19,7 @@ Patchwork provides a Docker-based environment for quick configuration of a development environment. This is the preferred installation method. To configure Patchwork using Docker: -1. Install **`docker`_** and **`docker-compose`_**. +1. Install `docker`_ and `docker-compose`_. 2. Build the images. This will download over 200MB from the internet: @@ -211,8 +211,8 @@ If you do not have `virtualenv` installed then you should install it now. This can be installed using the `python-virtualenv` or `python3-virtualenv` packages. Alternatively you can install these using `pip`. -It is also helpful to install [`tox`][ref-tox] which is used for running tests -in Patchwork. This can be installed using the `python-tox` or `python3-tox` +It is also helpful to install `tox` which is used for running tests in +Patchwork. This can be installed using the `python-tox` or `python3-tox` packages, or via `pip`. __ https://virtualenv.readthedocs.io/en/latest/