[PATCH] Improve documentation of delegation rules

[Stephen Finucane]

Per feedback from FOSDEM, this is still confusing some people. Clarify
things.

You might think we could just strip of the offending prefixes but that
might not always be the thing to do. Other VCSs don't include these
prefixes and both 'a' and 'b' are valid folder names. The risk of false
positives might be small, but it's enough to discourage us from doing
this.

Signed-off-by: Stephen Finucane <stephen at that.guru>
Cc: Thomas Monjalon <thomas.monjalon at 6wind.com>
---
 docs/usage/delegation.md                           | 48 +++++++++++++++-------
 .../0017_improved_delegation_rule_docs.py          | 32 +++++++++++++++
 patchwork/models.py                                | 13 ++++--
 3 files changed, 75 insertions(+), 18 deletions(-)
 create mode 100644 patchwork/migrations/0017_improved_delegation_rule_docs.py

diff --git a/docs/usage/delegation.md b/docs/usage/delegation.md
index 3643cd7..df64f96 100644
--- a/docs/usage/delegation.md
+++ b/docs/usage/delegation.md
@@ -2,7 +2,7 @@
 
 Autodelegation allows patches to be automatically delegated to a user based on
 the files modified by the patch. To do this, a number of rules can be
-configured in the project admininstration page. This can usually be found at
+configured in the project administration page. This can usually be found at
 `/admin/patchwork/project/<project_id>/change`.
 
 **NOTE:** Autodelegation can only be configured by Patchwork administrators,
@@ -11,17 +11,35 @@ autodelegation rules on a local instance, contact your Patchwork administrator.
 
 In this section there are the following fields:
 
-<dl>
-  <dt>Path</dt>
-  <dd>A path in <a href="https://docs.python.org/2/library/fnmatch.html">
-  fnmatch</a> format. The fnmatch library allows for limited, Unix shell-style
-  wildcarding</dd>
-  <dt>User</dt>
-  <dd>The patchwork user that should be autodelegated to the patch</dd>
-  <dt>Priority</dt>
-  <dd>The priority of the rule relative to other patches. Higher values
-  indicate higher priority</dd>
-</dl>
-
-Rules should be configured by setting the above fields and saving the rules.
-These rules will be applied at patch parse time.
+- User
+
+  The patchwork user that should be autodelegated to the patch
+
+- Priority
+
+  The priority of the rule relative to other patches. Higher values
+  indicate higher priority. If two rules have the same priority, ordering will
+  be based on the path.
+
+- Path
+
+  A path in [fnmatch](https://docs.python.org/2/library/fnmatch.html) format.
+  The fnmatch library allows for limited, Unix shell-style wildcarding.
+  Filenames are extracted from patch lines beginning with `--- ` or `+++ `.
+  Note that for projects using Git or Mercurial, the tools these VCS provide
+  for producing patches are prefixed with `a` or `b`. You should account for
+  this in your path. For example, to match the path `patchwork/views` (relative
+  to the top of a Git repo) your pattern should be:
+
+      ?/patchwork/views/*
+
+  It is also possible to use relative paths, such as:
+
+      */manage.py
+
+  For projects using other VCS like Subversion can simply use a bare path:
+
+     patchwork/views/*
+
+Rules are configured by setting the above fields and saving the rules. These
+rules will be applied at patch parse time.
diff --git a/patchwork/migrations/0017_improved_delegation_rule_docs.py b/patchwork/migrations/0017_improved_delegation_rule_docs.py
new file mode 100644
index 0000000..138b08f
--- /dev/null
+++ b/patchwork/migrations/0017_improved_delegation_rule_docs.py
@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+# Generated by Django 1.10.5 on 2017-02-08 00:19
+from __future__ import unicode_literals
+
+from django.conf import settings
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('patchwork', '0016_series_project'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='delegationrule',
+            name='path',
+            field=models.CharField(help_text=b'An fnmatch-style pattern to match filenames against', max_length=255),
+        ),
+        migrations.AlterField(
+            model_name='delegationrule',
+            name='priority',
+            field=models.IntegerField(default=0, help_text=b'The priority of the rule. Rules with a higher priority will override rules with lower priorities'),
+        ),
+        migrations.AlterField(
+            model_name='delegationrule',
+            name='user',
+            field=models.ForeignKey(help_text=b'A user to delegate the patch to.', on_delete=django.db.models.deletion.CASCADE, to=settings.AUTH_USER_MODEL),
+        ),
+    ]
diff --git a/patchwork/models.py b/patchwork/models.py
index ea40fbf..5950b19 100644
--- a/patchwork/models.py
+++ b/patchwork/models.py
@@ -100,10 +100,17 @@ class Project(models.Model):
 
 @python_2_unicode_compatible
 class DelegationRule(models.Model):
-    user = models.ForeignKey(User)
-    path = models.CharField(max_length=255)
     project = models.ForeignKey(Project)
-    priority = models.IntegerField(default=0)
+    user = models.ForeignKey(
+        User,
+        help_text='A user to delegate the patch to.')
+    path = models.CharField(
+        max_length=255,
+        help_text='An fnmatch-style pattern to match filenames against')
+    priority = models.IntegerField(
+        default=0,
+        help_text='The priority of the rule. Rules with a higher priority '
+        'will override rules with lower priorities')
 
     def __str__(self):
         return self.path
-- 
2.9.3