From eab1308d3fcf7046ad99634c648c3cec62a887c2 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Tue, 30 May 2017 15:48:13 +0100 Subject: docs: Document the various management commands available As requested. Signed-off-by: Stephen Finucane Reported-by: Thomas Monjalon Closes-bug: #77 --- docs/deployment/installation.rst | 6 ++ docs/deployment/management.rst | 135 +++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + docs/usage/overview.rst | 2 + 4 files changed, 144 insertions(+) create mode 100644 docs/deployment/management.rst (limited to 'docs') diff --git a/docs/deployment/installation.rst b/docs/deployment/installation.rst index 16cb41f..a570dd8 100644 --- a/docs/deployment/installation.rst +++ b/docs/deployment/installation.rst @@ -500,6 +500,8 @@ different sites and their corresponding domain names, which is required for the different emails sent by Patchwork (registration, password recovery) as well as the sample `pwclientrc` files provided by your project's page. +.. _deployment-parsemail: + Incoming Email -------------- @@ -635,6 +637,8 @@ services can be more than to get email into Patchwork. You can also create such as service yourself using a PaaS provider that supports incoming mail and writing a little web app. +.. _deployment-vcs: + (Optional) Configure your VCS to Automatically Update Patches ------------------------------------------------------------- @@ -653,6 +657,8 @@ If you are using a system other than Git, you can likely write a similar hook using `pwclient` to update patch state. If you do write one, please contribute it. +.. _deployment-cron: + (Optional) Configure the Patchwork Cron Job ------------------------------------------- diff --git a/docs/deployment/management.rst b/docs/deployment/management.rst new file mode 100644 index 0000000..c50b7b6 --- /dev/null +++ b/docs/deployment/management.rst @@ -0,0 +1,135 @@ +Management +========== + +This document describes the myriad administrative commands available with +Patchwork. Many of these commands are referenced in the :doc:`development +<../development/installation>` and :doc:`deployment ` +installation guides. + +The ``manage.py`` Script +------------------------ + +Django provides the ``django-admin`` command-line utility for interacting with +Django applications and projects, as described in the `Django documentation`_. +Patchwork, being a Django application, provides a wrapper for this command - +``manage.py`` - that exposes not only the management commands of Django and its +default applications, but also a number of custom, Patchwork-only management +commands. + +An overview of the Patchwork-specific commands is provided below. For +information on the commands provided by Django itself, refer to the `Django +documentation`_. Information on any command can also be found by passing the +``--help`` parameter: + +.. code-block:: shell + + ./manage.py cron --help + +.. _Django documentation: https://docs.djangoproject.com/en/1.8/ref/django-admin/ + +Available Commands +------------------ + +cron +~~~~ + +.. program:: manage.py cron + +.. code-block:: shell + + ./manage.py cron + +Run periodic Patchwork functions: send notifications and expire unused users. + +This is required to ensure notifications emails are actually sent to users that +request them and is helpful to expire unused users created by spambots. For +more information on integration of this script, refer to the :ref:`deployment +installation guide `. + +parsearchive +~~~~~~~~~~~~ + +.. program:: manage.py parseachive + +Parse an mbox archive file and store any patches/comments found. + +.. code-block:: shell + + ./manage.py parsearchive [--list-id ] + +This is mostly useful for development or for adding message that were missed +due to, for example, an outage. + +.. option:: --list-id + + mailing list ID. If not supplied, this will be extracted from the mail + headers. + +.. option:: infile + + input mbox filename + +parsemail +~~~~~~~~~ + +.. program:: manage.py parsemail + +Parse an mbox file and store any patch/comment found. + +.. code-block:: shell + + ./manage.py parsemail [--list-id ] + +This is the main script used to get mails (and therefore patches) into +Patchwork. It is generally used by the ``parsemail.sh`` script in combination +with a mail transfer agent (MTA) like Postfix. For more information, refer to +the :ref:`deployment installation guide `. + +.. option:: --list-id + + mailing list ID. If not supplied, this will be extracted from the mail + headers. + +.. option:: infile + + input mbox filename. If not supplied, a patch will be read from ``stdin``. + +rehash +~~~~~~ + +.. program:: manage.py rehash + +Update the hashes on existing patches. + +.. code-block:: shell + + ./manage.py rehash [, ...] + +Patchwork stores hashes for each patch it receives. These hashes can be used to +uniquely identify a patch for things like :ref:`automatically changing the +state of the patch in Patchwork when it merges `. If you change +your hashing algorithm, you may wish to rehash the patches. + +.. option:: patch_id + + a patch ID number. If not supplied, all patches will be updated. + +retag +~~~~~ + +.. program:: manage.py retag + +Update the tag (Ack/Review/Test) counts on existing patches. + +.. code-block:: shell + + ./manage.py retag [...] + +Patchwork extracts :ref:`tags ` from each patch it receives. By +default, three tags are extracted, but it's possible to change this on a +per-instance basis. Should you add additional tags, you may wish to scan older +patches for these new tags. + +.. option:: patch_id + + a patch ID number. If not supplied, all patches will be updated. diff --git a/docs/index.rst b/docs/index.rst index 623b683..5a7bcda 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -37,6 +37,7 @@ of community projects. deployment/installation deployment/configuration + deployment/management deployment/upgrading .. _development-docs: diff --git a/docs/usage/overview.rst b/docs/usage/overview.rst index 40f49e1..6d9117c 100644 --- a/docs/usage/overview.rst +++ b/docs/usage/overview.rst @@ -105,6 +105,8 @@ one delegate can be assigned to a patch. Patchwork supports automatic delegation of patches. Refer to :doc:`delegation` for more information. +.. _overview-tags: + Tags ~~~~ -- cgit v1.2.3