diff options
| -rw-r--r-- | docs/development/contributing.rst | 55 | ||||
| -rw-r--r-- | docs/development/installation.rst | 3 | ||||
| -rw-r--r-- | 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 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. |