docs: Update release, contributing guides

Document the requirement to send an email to the list upon a release and
to always send patches via email.

Signed-off-by: Stephen Finucane <stephen@that.guru>
Acked-by: Daniel Axtens <dja@axtens.net>

3 files changed, 63 insertions, 19 deletions

diff --git a/docs/development/contributing.rst b/docs/development/contributing.rst
index c311cfe..7e2a72c 100644
--- a/docs/development/contributing.rst
+++ b/docs/development/contributing.rst
@@ -19,24 +19,26 @@ Testing
 -------
 
 Patchwork includes a `tox`_ script to automate testing. This requires a
-functional database and some Python requirements like `tox`. Refer to
+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:
+You may also need to install *tox*. If so, do this now:
 
 .. code-block:: shell
 
-   $ sudo pip install tox
+   $ pip install --user tox
 
 .. tip::
 
-   If you're using Docker, you may not need to install `tox`
+   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:
+   container. For Docker, you can run *tox* like so:
 
    .. code-block:: shell
 
-      $ docker-compose run web tox [ARGS...]
+      $ docker-compose run --rm web tox [ARGS...]
+
+   For more information, refer to :ref:`installation-docker`.
 
 Assuming these requirements are met, actually testing Patchwork is quite easy
 to do. To start, you can show the default targets like so:
@@ -70,17 +72,18 @@ this:
 
    $ tox
 
+
 .. _release-notes:
 
 Release Notes
 -------------
 
-Patchwork uses `reno`_ for release note management. To use `reno`, you must
+Patchwork uses `reno`_ for release note management. To use *reno*, you must
 first install it:
 
 .. code-block:: shell
 
-   $ sudo pip install reno
+   $ pip install --user reno
 
 Once installed, a new release note can be created using the ``reno new``
 command:
@@ -92,6 +95,7 @@ command:
 Modify the created file, removing any irrelevant sections, and include the
 modified file in your change.
 
+
 API
 ---
 
@@ -106,13 +110,21 @@ for more information.
     All API changes should be called out in :ref:`release notes
     <release-notes>` using the ``api`` section.
 
+
+Reporting Issues
+----------------
+
+You can report issues to the :ref:`mailing list <mailing-lists>` or the `GitHub
+issue tracker`_.
+
+
 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:
+All patches should be sent to the :ref:`mailing list <mailing-lists>`. You must
+be subscribed to the list in order to submit patches. 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>`
 
@@ -120,8 +132,25 @@ ensure:
 
 * :ref:`A release note is included <release-notes>`
 
+Patches should ideally be submitted using the *git send-email* tool.
+
+
+.. _mailing-lists:
+
+Mailing Lists
+-------------
+
+Patchwork uses a single mailing list for development, questions and
+announcements.
+
+    patchwork@lists.ozlabs.org
+
+Further information about the Patchwork mailing list is available can be found on
+`lists.ozlabs.org`_.
+
 .. _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/
+.. _GitHub issue tracker: https://github.com/getpatchwork/patchwork
+.. _lists.ozlabs.org: https://lists.ozlabs.org/listinfo/patchwork
diff --git a/docs/development/installation.rst b/docs/development/installation.rst
index f857ff6..1a97b6d 100644
--- a/docs/development/installation.rst
+++ b/docs/development/installation.rst
@@ -12,6 +12,9 @@ To begin, you should clone Patchwork:
 
    $ git clone git://github.com/getpatchwork/patchwork.git
 
+
+.. _installation-docker:
+
 Docker-Based Installation
 -------------------------
 
diff --git a/docs/development/releasing.rst b/docs/development/releasing.rst
index eb33bbf..86cacb3 100644
--- a/docs/development/releasing.rst
+++ b/docs/development/releasing.rst
@@ -43,21 +43,26 @@ These version numbers are exposed via the API and it's possible to request a
 specific version in the URL. Refer to the `API Guide <../api/rest>` for more
 information.
 
+
 Release Cycle
 -------------
 
 There is no cadence for releases: they are made available as necessary.
 
+
 Supported Versions
 ------------------
 
-Typically all development should occur on `master`. While we will backport
+Typically all development should occur on ``master``. While we will backport
 bugfixes and security updates, we will not backport any new features. This is
 to ensure stability for users of these versions of Patchwork.
 
+
 Release Checklist
 -----------------
 
+The follow steps apply to all releases:
+
 * Documentation has been updated with latest release version
 
 * Documentation references latest supported version of Django
@@ -73,22 +78,29 @@ Release Checklist
 * A `GitHub Release`__, with text corresponding to an abbreviated form of the
   release notes for that cycle, has been created
 
-The following only apply to full releases, or those where the `MAJOR` or
-`MINOR` number is incremented:
+* An email describing the release and top-level overview of the changes has
+  been sent to the mailing list. Refer to the emails for `Patchwork v2.0.0`__
+  and `Patchwork v2.0.1`__ for examples.
+
+The following only apply to full releases, or those where the **MAJOR** or
+**MINOR** number is incremented:
 
-* A new branch called `stable/MAJOR.MINOR` has been created from the tagged
+* A new branch called ``stable/MAJOR.MINOR`` has been created from the tagged
   commit
 
 Once released, bump the version found in ``patchwork/__init__.py`` once again.
 
 __ https://git-scm.com/book/en/v2/Git-Basics-Tagging
 __ https://github.com/getpatchwork/patchwork/releases/new
+__ https://lists.ozlabs.org/pipermail/patchwork/2017-August/004549.html
+__ https://lists.ozlabs.org/pipermail/patchwork/2017-December/004683.html
+
 
 Backporting
 -----------
 
 We will occasionally backport bugfixes and security updates. When backporting a
-patch, said patch should first be merged into `master`. Once merged, you can
+patch, said patch should first be merged into ``master``. Once merged, you can
 backport by cherry-picking commits, using the ``-x`` flag for posterity:
 
 .. code-block:: shell
@@ -101,5 +113,5 @@ when committing::
    Conflicts
            patchwork/bin/pwclient
 
-When enough patches have been backported, you should release a new `PATCH`
+When enough patches have been backported, you should release a new **PATCH**
 release.