MAINTAINERS: Clarify the meaning of nested maintainership

Clarify the meaning of nested maintainership.

Signed-off-by: George Dunlap <george.dunlap@citrix.com>
---
We had a discussion about the meaning of nested maintainership at the
recent Xen Hackathon.  The notes of that meeting can be found on this
list [1].  No decision is official until discussed on this list, so
consider this patch the official proposal for this change, and object
or ask for clarification accordingly.

Compared to v1, there is one change that is worth pointing out: The
claim that THE REST consists of all committers.  This is the case at
the moment, but this change would codify that this is an invariant we
intend to keep going forward.

The advantage of this is that the dispute resolution mentioned in this
patch for maintainers who can't agree lines up directly with the
fall-back for broader community issues upon which we can't reach
consensus.

[1] marc.info/?i=<EDB48431-C3EF-4461-B2D2-3AB95EA6C392@gmail.com>

Changes in v2:
- fixed spelling of "maintainer"
- fixed path of multi.c
- clarified that the resolution by REST would be by *majority* vote
- Asserted that The REST consists of all committers

CC: Ian Jackson <ian.jackson@eu.citrix.com>
CC: Jan Beulich <jbeulich@suse.com>
CC: Keir Fraser <keir@xen.org>
CC: Tim Deegan <tim@xen.org>
CC: Wei Liu <wei.liu2@citrix.com>
CC: Konrad Wilk <konrad.wilk@oracle.com>
CC: Andrew Cooper <andrew.cooper3@citrix.com>
CC: Lars Kurth <lars.kurth@citrix.com>

diff --git a/MAINTAINERS b/MAINTAINERS
index de482eace15cc2fcefcaecea983861e0eb3c8ebb..3be61548a66282ebe6157ea1e38bd973eb7c6d14 100644 (file)
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -94,6 +94,40 @@ Descriptions of section entries:
              printk, pr_info or pr_err
           One regex pattern per line.  Multiple K: lines acceptable.
 
+
+The meaning of nesting:
+
+Many maintainership areas are "nested": for example, there are entries
+for xen/arch/x86 as well as xen/arch/x86/mm, and even
+xen/arch/x86/mm/shadow; and there is a section at the end called "THE
+REST" which lists all committers.  The meaning of nesting is that:
+
+1. Under normal circumstances, the Ack of the most specific maintainer
+is both necessary and sufficient to get a change to a given file
+committed.  So a change to xen/arch/x86/mm/shadow/multi.c requires the
+the Ack of the xen/arch/x86/mm/shadow maintainer for that part of the
+patch, but would not require the Ack of the xen/arch/x86 maintainer or
+the xen/arch/x86/mm maintainer.
+
+(A patch of course needs acks from the maintainers of each file that
+it changes; so a patch which changes xen/arch/x86/traps.c,
+xen/arch/x86/mm/p2m.c, and xen/arch/x86/mm/shadow/multi.c would
+require an Ack from each of the three sets of maintainers.)
+
+2. In unusual circumstances, a more general maintainer's Ack can stand
+in for or even overrule a specific maintainer's Ack.  Unusual
+circumstances might include:
+ - The patch is fixing a high-priority issue causing immediate pain,
+ and the more specific maintainer is not available.
+ - The more specific maintainer has not responded either to the
+ original patch, nor to "pings", within a reasonable amount of time.
+ - The more general maintainer wants to overrule the more specific
+ maintainer on some issue. (This should be exceptional.)
+ - In the case of a disagreement between maintainers, THE REST can
+ settle the matter by majority vote.  (This should be very exceptional
+ indeed.)
+
+
 Maintainers List (try to look for most precise areas first)
 
                -----------------------------------