Improve documentation of delegation rules

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@that.guru>
Reviewed-by: Thomas Monjalon <thomas.monjalon@6wind.com>

3 files changed, 74 insertions, 18 deletions

diff --git a/docs/usage/delegation.md b/docs/usage/delegation.md
index 3643cd7..7e86cfb 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 VCSs 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..9d70806
--- /dev/null
+++ b/patchwork/migrations/0017_improved_delegation_rule_docs.py
@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+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..5add017 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