[PATCH v2 1/3] docs: Update release, contributing guides
Stephen Finucane
stephen at that.guru
Thu May 17 19:36:02 AEST 2018
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 at that.guru>
---
v2:
- Fix two typos from v1
---
docs/development/contributing.rst | 55 +++++++++++++++++++++++--------
docs/development/installation.rst | 3 ++
docs/development/releasing.rst | 24 ++++++++++----
3 files changed, 63 insertions(+), 19 deletions(-)
diff --git a/docs/development/contributing.rst b/docs/development/contributing.rst
index c311cfe0..7e2a72cf 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 at 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 f857ff6f..1a97b6de 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 eb33bbf7..86cacb3a 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.
--
2.17.0
More information about the Patchwork
mailing list