From 265040867d5da2726b712c3decb8641c650598db Mon Sep 17 00:00:00 2001
From: Stephen Finucane <stephen@that.guru>
Date: Tue, 7 Feb 2017 21:45:56 +0000
Subject: 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>
---
 docs/usage/delegation.md | 48 +++++++++++++++++++++++++++++++++---------------
 1 file changed, 33 insertions(+), 15 deletions(-)

(limited to 'docs/usage')

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.
-- 
cgit v1.2.3