[PATCH 5/5] docs: Add delegation guide

[Stephen Finucane]

On Mon, 2016-11-28 at 15:43 +0100, Thomas Monjalon wrote:
> Hi,
> 
> 2016-10-11 19:01, Stephen Finucane:
> > We do autodelegation - let's tell people all about it.
> 
> I am reading this documentation at
> https://patchwork.readthedocs.io/en/latest/usage/delegation/
> I have two questions about this feature.
> 
> Is the path starting with a slash?

To be honest, I'm not 100% sure but I would guess no - the paths found
in mails are relative Git paths and we store them as is. However, you'd
probably want to use wildcards anyway unless you're being very
specific. For example, you can delegate this file:

    patchwork/views/cover.py

with varying levels of accuracy using any of these below patterns (and
many more beside):

    *.py
    */cover.py
    patchwork/views/*
    patchwork/views/cover.py
    patchwork/views/*.py
    */views/*

> What happens if a file does not match any rule?

Nothing. The file must be delegated manually, just as before.

> What happens if two files match two rules leading to the same user?

Only one rule will ever be applied. Rules have a 'priority' field,
which is used first (higher values are applied first). In the event of
a conflict, the 'path' field will take priority, alphabetically
ordered. As such, using the above rules, the first will take priority.
This can be confirmed by checking Python's sorting yourself:

    $ python
    >>> paths = ['*.py', '*/cover.py', ..., '*/views/*']
    >>> sorted(paths)
    ['*.py', '*/cover.py', '*/views/*', ...]

> What happens if two files match two rules leading to different users?

Won't happen. See above.

Stephen