[PATCH v4 1/1] management: introduce replacerelations command

[Daniel Axtens]

> 1) `docker-compose run web --tox` fails, both pep8 and in some of the
> substantive tests:
>
> Creating test database for alias 'default'...
> System check identified no issues (0 silenced).
> .............................................................................................................................................................................................................................................................................Invalid path: xyz123random
> .F..........................................................................................................................................................................................................................................s................................................................................

I think this might be because by the time you get to your test, a number
of patches have been created and destroyed, so the patches are no longer
numbered the way you expect. I didn't pick this up before because last
time I ran the tests there was only the one with the invalid path.

> 3) I reformatted the docs to wrap at 80 columns and I made some minor
> changes to the wording and punctuation in the process. Please wrap
> future changes at 80 columns. I also found that the patch groups file
> doesn't render as separate lines in a web browser, it renders as

I screwed up the suggested docs, try this one instead.

Kind regards,
Daniel

diff --git a/docs/deployment/management.rst b/docs/deployment/management.rst
index 9c57f1962283..dcee9ff518f6 100644
--- a/docs/deployment/management.rst
+++ b/docs/deployment/management.rst
@@ -116,6 +116,43 @@ the :ref:`deployment installation guide <deployment-parsemail>`.
 
    input mbox filename. If not supplied, a patch will be read from ``stdin``.
 
+replacerelations
+~~~~~~~~~~~~~~~~
+
+.. program:: manage.py replacerelations
+
+Parse a patch groups file and store any relation found
+
+.. code-block:: shell
+
+    ./manage.py replacerelations <infile>
+
+This is a script used to ingest relations into Patchwork.
+
+A patch groups file contains on each line a list of space separated patch IDs
+of patches that form a relation.
+
+For example, consider the contents of a sample patch groups file::
+
+    1 3 5
+    2
+    7 10 11 12
+
+In this case the script will identify 2 relations, (1, 3, 5) and
+(7, 10, 11, 12). The single patch ID "2" on the second line is ignored as a
+relation always consists of more than 1 patch.
+
+Further, if a patch ID in the patch groups file does not exist in the database
+of the Patchwork instance, that patch ID will be silently ignored while forming
+the relations.
+
+Running this script will remove all existing relations and replace them with
+the relations found in the file.
+
+.. option:: infile
+
+    input patch groups file.
+
 rehash
 ~~~~~~