[PATCH] MAINTAINERS: Clarify the meaning of nested maintainership

[PATCH] MAINTAINERS: Clarify the meaning of nested maintainership

[George Dunlap]

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.

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

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>
---
 MAINTAINERS | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/MAINTAINERS b/MAINTAINERS
index a34685d..be901d5 100644
--- 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 maintanership 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, as well as a few more.  The meaning
+of nesting is that:
+
+1. Under normal circumstances, the Ack of the most specific maintaner
+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/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
+ vote to settle the matter.  (This should be very exceptional indeed.)
+
+
 Maintainers List (try to look for most precise areas first)
 
 		-----------------------------------
-- 
2.1.4


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

Re: [PATCH] MAINTAINERS: Clarify the meaning of nested maintainership

[Lars Kurth]

On 21/04/2016 17:03, "George Dunlap" <george.dunlap@citrix.com> wrote:

>Clarify the meaning of nested maintainership.
>
>Signed-off-by: George Dunlap <george.dunlap@citrix.com>
>---
>
> MAINTAINERS | 34 ++++++++++++++++++++++++++++++++++
> 1 file changed, 34 insertions(+)
>
>diff --git a/MAINTAINERS b/MAINTAINERS
>index a34685d..be901d5 100644
>--- 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:
>+
>
>[snip]

>+ - In the case of a disagreement between maintainers, THE REST can
>+ vote to settle the matter.  (This should be very exceptional indeed.)

This creates a slight conflict with the project governance, which states
that committers act as referees in case of disagreements. As REST
maintainers are a superset of committers, this could create a potential
mismatch.

Given, that the text says "can", I don't have an issue with it. It merely
adds an extra level of complexity when it comes to resolving disagreements
and maybe could be confusing.

Regards
Lars

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

Re: [PATCH] MAINTAINERS: Clarify the meaning of nested maintainership

[Juergen Gross]

On 21/04/16 18:03, George Dunlap wrote:
> 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.
> 
> [1] marc.info/?i=<EDB48431-C3EF-4461-B2D2-3AB95EA6C392@gmail.com>
> 
> 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>
> ---
>  MAINTAINERS | 34 ++++++++++++++++++++++++++++++++++
>  1 file changed, 34 insertions(+)
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index a34685d..be901d5 100644
> --- 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 maintanership 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, as well as a few more.  The meaning
> +of nesting is that:
> +
> +1. Under normal circumstances, the Ack of the most specific maintaner
> +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/multi.c would require an

xen/arch/x86/mm/shadow/multi.c


Juergen

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

Re: [PATCH] MAINTAINERS: Clarify the meaning of nested maintainership

[Jan Beulich]

>>> On 21.04.16 at 18:03, <george.dunlap@citrix.com> wrote:
> Clarify the meaning of nested maintainership.
> 
> Signed-off-by: George Dunlap <george.dunlap@citrix.com>

With the minor corrections suggested by Lars and Jürgen,
Acked-by: Jan Beulich <jbeulich@suse.com>

Thanks for this nice summary!

Jan

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

Re: [PATCH] MAINTAINERS: Clarify the meaning of nested maintainership

[Andrew Cooper]

On 21/04/16 17:03, George Dunlap wrote:
> 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.
>
> [1] marc.info/?i=<EDB48431-C3EF-4461-B2D2-3AB95EA6C392@gmail.com>
>
> 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>

With Juergen's correction, Reviewed-by: Andrew Cooper
<andrew.cooper3@citrix.com>

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

Re: [PATCH] MAINTAINERS: Clarify the meaning of nested maintainership

[Julien Grall]

Hi George,

On 21/04/16 17:03, George Dunlap wrote:
> 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.
>
> [1] marc.info/?i=<EDB48431-C3EF-4461-B2D2-3AB95EA6C392@gmail.com>
>
> 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>
> ---
>   MAINTAINERS | 34 ++++++++++++++++++++++++++++++++++
>   1 file changed, 34 insertions(+)
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index a34685d..be901d5 100644
> --- 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 maintanership areas are "nested": for example, there are entries

NIT: s/maintanership/maintainership/

> +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, as well as a few more.  The meaning
> +of nesting is that:
> +
> +1. Under normal circumstances, the Ack of the most specific maintaner

NIT: s/maintaner/maintainer/

Regards,

-- 
Julien Grall

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

Re: [PATCH] MAINTAINERS: Clarify the meaning of nested maintainership

[George Dunlap]

On 21/04/16 17:59, Lars Kurth wrote:
> 
> 
> On 21/04/2016 17:03, "George Dunlap" <george.dunlap@citrix.com> wrote:
> 
>> Clarify the meaning of nested maintainership.
>>
>> Signed-off-by: George Dunlap <george.dunlap@citrix.com>
>> ---
>>
>> MAINTAINERS | 34 ++++++++++++++++++++++++++++++++++
>> 1 file changed, 34 insertions(+)
>>
>> diff --git a/MAINTAINERS b/MAINTAINERS
>> index a34685d..be901d5 100644
>> --- 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:
>> +
>>
>> [snip]
> 
>> + - In the case of a disagreement between maintainers, THE REST can
>> + vote to settle the matter.  (This should be very exceptional indeed.)
> 
> This creates a slight conflict with the project governance, which states
> that committers act as referees in case of disagreements. As REST
> maintainers are a superset of committers, this could create a potential
> mismatch.
> 
> Given, that the text says "can", I don't have an issue with it. It merely
> adds an extra level of complexity when it comes to resolving disagreements
> and maybe could be confusing.

With Keir gone, is that actually the case anymore?  I think at the
moment REST == committers.

And the logic behind putting the committers under the REST seemed to me
in part to make the logic match up.

 -George

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

Re: [PATCH] MAINTAINERS: Clarify the meaning of nested maintainership

[Lars Kurth]

On 26/04/2016 17:19, "George Dunlap" <george.dunlap@citrix.com> wrote:

>On 21/04/16 17:59, Lars Kurth wrote:
>> 
>> 
>> On 21/04/2016 17:03, "George Dunlap" <george.dunlap@citrix.com> wrote:
>> 
>>> Clarify the meaning of nested maintainership.
>>>
>>> Signed-off-by: George Dunlap <george.dunlap@citrix.com>
>>> ---
>>>
>>> MAINTAINERS | 34 ++++++++++++++++++++++++++++++++++
>>> 1 file changed, 34 insertions(+)
>>>
>>> diff --git a/MAINTAINERS b/MAINTAINERS
>>> index a34685d..be901d5 100644
>>> --- 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:
>>> +
>>>
>>> [snip]
>> 
>>> + - In the case of a disagreement between maintainers, THE REST can
>>> + vote to settle the matter.  (This should be very exceptional indeed.)
>> 
>> This creates a slight conflict with the project governance, which states
>> that committers act as referees in case of disagreements. As REST
>> maintainers are a superset of committers, this could create a potential
>> mismatch.
>> 
>> Given, that the text says "can", I don't have an issue with it. It
>>merely
>> adds an extra level of complexity when it comes to resolving
>>disagreements
>> and maybe could be confusing.
>
>With Keir gone, is that actually the case anymore?  I think at the
>moment REST == committers.
>
>And the logic behind putting the committers under the REST seemed to me
>in part to make the logic match up.

That is fine with me. I just picked up on it, because further up the patch
you said

+Many maintanership 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, as well as a few more.
                                   ^^^^^^^^^^^^^^^^^^^^^

Lars

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

Re: [PATCH] MAINTAINERS: Clarify the meaning of nested maintainership

[George Dunlap]

On 26/04/16 17:57, Lars Kurth wrote:
> 
> 
> On 26/04/2016 17:19, "George Dunlap" <george.dunlap@citrix.com> wrote:
> 
>> On 21/04/16 17:59, Lars Kurth wrote:
>>>
>>>
>>> On 21/04/2016 17:03, "George Dunlap" <george.dunlap@citrix.com> wrote:
>>>
>>>> Clarify the meaning of nested maintainership.
>>>>
>>>> Signed-off-by: George Dunlap <george.dunlap@citrix.com>
>>>> ---
>>>>
>>>> MAINTAINERS | 34 ++++++++++++++++++++++++++++++++++
>>>> 1 file changed, 34 insertions(+)
>>>>
>>>> diff --git a/MAINTAINERS b/MAINTAINERS
>>>> index a34685d..be901d5 100644
>>>> --- 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:
>>>> +
>>>>
>>>> [snip]
>>>
>>>> + - In the case of a disagreement between maintainers, THE REST can
>>>> + vote to settle the matter.  (This should be very exceptional indeed.)
>>>
>>> This creates a slight conflict with the project governance, which states
>>> that committers act as referees in case of disagreements. As REST
>>> maintainers are a superset of committers, this could create a potential
>>> mismatch.
>>>
>>> Given, that the text says "can", I don't have an issue with it. It
>>> merely
>>> adds an extra level of complexity when it comes to resolving
>>> disagreements
>>> and maybe could be confusing.
>>
>> With Keir gone, is that actually the case anymore?  I think at the
>> moment REST == committers.
>>
>> And the logic behind putting the committers under the REST seemed to me
>> in part to make the logic match up.
> 
> That is fine with me. I just picked up on it, because further up the patch
> you said
> 
> +Many maintanership 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, as well as a few more.

OK -- I'll modify that, and put a note to be discussed in the resubmission.

 -George


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel