[Linux-kernel-mentees] Adding doc for parse-maintainers.pl

[Linux-kernel-mentees] Adding doc for parse-maintainers.pl

[Aditya]

Hi Sir
So, I tried finding doc where to add documentation for
parse-maintainers.pl and MAINTAINERS.
I think the only place we have documentation related to MAINTAINERS is
here:
https://www.kernel.org/doc/html/latest/process/maintainers.html

Or https://www.kernel.org/doc/linux/MAINTAINERS

Maybe we should add the changes at the end of this section:
https://www.kernel.org/doc/html/latest/process/maintainers.html#descriptions-of-section-entries-and-preferred-order

ie at the end of "Descriptions of section entries and preferred
order", something like: You can achieve this desired order using
/scripts/parse-maintainers.pl


What do you think/suggest?

--
Thanks
Aditya
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Re: [Linux-kernel-mentees] Adding doc for parse-maintainers.pl

[Lukas Bulwahn]

[-- Attachment #1.1: Type: text/plain, Size: 882 bytes --]

On Mi., 18. Nov. 2020 at 19:02, Aditya <yashsri421@gmail.com> wrote:

> Hi Sir
> So, I tried finding doc where to add documentation for
> parse-maintainers.pl and MAINTAINERS.
> I think the only place we have documentation related to MAINTAINERS is
> here:
> https://www.kernel.org/doc/html/latest/process/maintainers.html
>
> Or https://www.kernel.org/doc/linux/MAINTAINERS
>
> Maybe we should add the changes at the end of this section:
>
> https://www.kernel.org/doc/html/latest/process/maintainers.html#descriptions-of-section-entries-and-preferred-order
>
> ie at the end of "Descriptions of section entries and preferred
> order", something like: You can achieve this desired order using
> /scripts/parse-maintainers.pl
>
>
> What do you think/suggest?
>

That is good.

We can more documentation on parse-maintainers in a new separate page.

Lukas


> --
> Thanks
> Aditya
>

[-- Attachment #1.2: Type: text/html, Size: 2003 bytes --]

[-- Attachment #2: Type: text/plain, Size: 201 bytes --]

_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Re: [Linux-kernel-mentees] Adding doc for parse-maintainers.pl

[Lukas Bulwahn]

On Wed, Nov 18, 2020 at 8:12 PM Lukas Bulwahn <lukas.bulwahn@gmail.com> wrote:
>
>
>
> On Mi., 18. Nov. 2020 at 19:02, Aditya <yashsri421@gmail.com> wrote:
>>
>> Hi Sir
>> So, I tried finding doc where to add documentation for
>> parse-maintainers.pl and MAINTAINERS.
>> I think the only place we have documentation related to MAINTAINERS is
>> here:
>> https://www.kernel.org/doc/html/latest/process/maintainers.html
>>
>> Or https://www.kernel.org/doc/linux/MAINTAINERS
>>
>> Maybe we should add the changes at the end of this section:
>> https://www.kernel.org/doc/html/latest/process/maintainers.html#descriptions-of-section-entries-and-preferred-order
>>

I hope you did realize that the two pages:

https://www.kernel.org/doc/html/latest/process/maintainers.html
https://www.kernel.org/doc/linux/MAINTAINERS

come from the same source file, it is simply the MAINTAINERS file in
the root directory of the git repository that is then processed and
placed to those locations above.

So, you only need to modify MAINTAINERS and send a patch.

I suggest you write up and summarize what parse-maintainers does.

>> ie at the end of "Descriptions of section entries and preferred
>> order", something like: You can achieve this desired order using
>> /scripts/parse-maintainers.pl
>>
>>
>> What do you think/suggest?
>
>
> That is good.
>
> We can more documentation on parse-maintainers in a new separate page.
>
> Lukas
>
>>
>> --
>> Thanks
>> Aditya
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

[Linux-kernel-mentees] [PATCH] Documentation: MAINTAINERS: add information about parse-maintainers.pl

[Aditya Srivastava]

parse-maintainers.pl is a script which can be used to automatically
order the contents of MAINTAINERS file in preferred order (i.e.
'MRLSWQBCPTFXNK').

But currently we don't have a documentation on it.

Add documentation regarding the same in MAINTAINERS file.

Signed-off-by: Aditya Srivastava <yashsri421@gmail.com>
---
the patch applies perfectly on latest next-20201119

 MAINTAINERS | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/MAINTAINERS b/MAINTAINERS
index 5db753fa1295..7ad00af7acd4 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -136,6 +136,9 @@ Descriptions of section entries and preferred order
 	      printk, pr_info or pr_err
 	   One regex pattern per line.  Multiple K: lines acceptable.
 
+This order can be generated automatically for you using
+``scripts/parse-maintainers.pl``.
+
 Maintainers List
 ----------------
 
-- 
2.17.1

_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Re: [Linux-kernel-mentees] [PATCH] Documentation: MAINTAINERS: add information about parse-maintainers.pl

[Aditya]

On 20/11/20 3:42 pm, Aditya Srivastava wrote:
> parse-maintainers.pl is a script which can be used to automatically
> order the contents of MAINTAINERS file in preferred order (i.e.
> 'MRLSWQBCPTFXNK').
> 
> But currently we don't have a documentation on it.
> 
> Add documentation regarding the same in MAINTAINERS file.
> 
> Signed-off-by: Aditya Srivastava <yashsri421@gmail.com>
> ---
> the patch applies perfectly on latest next-20201119
> 
>  MAINTAINERS | 3 +++
>  1 file changed, 3 insertions(+)
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 5db753fa1295..7ad00af7acd4 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -136,6 +136,9 @@ Descriptions of section entries and preferred order
>  	      printk, pr_info or pr_err
>  	   One regex pattern per line.  Multiple K: lines acceptable.
>  
> +This order can be generated automatically for you using
> +``scripts/parse-maintainers.pl``.
> +
>  Maintainers List
>  ----------------
>  
> 

Rationale for my changes:
I did not go into much detail of its working here.
A bit detail on this can be to use 'scripts/parse-maintainers
--sorted' which produces the sorted file in MAINTAINERS.new by
default. The input and output default files can be changed using
'--input' and '--output' options. However, here I have omitted these
details as running with '--help' option already provides this
information in detail.
So just making user aware of the script should serve our purpose.

What do you think?

Thanks
Aditya
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Re: [Linux-kernel-mentees] [PATCH] Documentation: MAINTAINERS: add information about parse-maintainers.pl

[Lukas Bulwahn]

On Fri, Nov 20, 2020 at 11:16 AM Aditya <yashsri421@gmail.com> wrote:
>
> On 20/11/20 3:42 pm, Aditya Srivastava wrote:
> > parse-maintainers.pl is a script which can be used to automatically
> > order the contents of MAINTAINERS file in preferred order (i.e.
> > 'MRLSWQBCPTFXNK').
> >
> > But currently we don't have a documentation on it.
> >
> > Add documentation regarding the same in MAINTAINERS file.
> >
> > Signed-off-by: Aditya Srivastava <yashsri421@gmail.com>
> > ---
> > the patch applies perfectly on latest next-20201119
> >
> >  MAINTAINERS | 3 +++
> >  1 file changed, 3 insertions(+)
> >
> > diff --git a/MAINTAINERS b/MAINTAINERS
> > index 5db753fa1295..7ad00af7acd4 100644
> > --- a/MAINTAINERS
> > +++ b/MAINTAINERS
> > @@ -136,6 +136,9 @@ Descriptions of section entries and preferred order
> >             printk, pr_info or pr_err
> >          One regex pattern per line.  Multiple K: lines acceptable.
> >
> > +This order can be generated automatically for you using
> > +``scripts/parse-maintainers.pl``.
> > +
> >  Maintainers List
> >  ----------------
> >
> >
>
> Rationale for my changes:
> I did not go into much detail of its working here.
> A bit detail on this can be to use 'scripts/parse-maintainers
> --sorted' which produces the sorted file in MAINTAINERS.new by
> default. The input and output default files can be changed using
> '--input' and '--output' options. However, here I have omitted these
> details as running with '--help' option already provides this
> information in detail.
> So just making user aware of the script should serve our purpose.
>
> What do you think?
>

It makes sense not to put that into MAINTAINERS.

Do you understand how to use ./scripts/parse-maintainers, though?

So if the warning with checkpatch is shown on a patch, what would you
need to execute to get a corrected patch?

Lukas
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Re: [Linux-kernel-mentees] [PATCH] Documentation: MAINTAINERS: add information about parse-maintainers.pl

[Aditya]

On 21/11/20 3:27 pm, Lukas Bulwahn wrote:
> On Fri, Nov 20, 2020 at 11:16 AM Aditya <yashsri421@gmail.com> wrote:
>>
>> On 20/11/20 3:42 pm, Aditya Srivastava wrote:
>>> parse-maintainers.pl is a script which can be used to automatically
>>> order the contents of MAINTAINERS file in preferred order (i.e.
>>> 'MRLSWQBCPTFXNK').
>>>
>>> But currently we don't have a documentation on it.
>>>
>>> Add documentation regarding the same in MAINTAINERS file.
>>>
>>> Signed-off-by: Aditya Srivastava <yashsri421@gmail.com>
>>> ---
>>> the patch applies perfectly on latest next-20201119
>>>
>>>  MAINTAINERS | 3 +++
>>>  1 file changed, 3 insertions(+)
>>>
>>> diff --git a/MAINTAINERS b/MAINTAINERS
>>> index 5db753fa1295..7ad00af7acd4 100644
>>> --- a/MAINTAINERS
>>> +++ b/MAINTAINERS
>>> @@ -136,6 +136,9 @@ Descriptions of section entries and preferred order
>>>             printk, pr_info or pr_err
>>>          One regex pattern per line.  Multiple K: lines acceptable.
>>>
>>> +This order can be generated automatically for you using
>>> +``scripts/parse-maintainers.pl``.
>>> +
>>>  Maintainers List
>>>  ----------------
>>>
>>>
>>
>> Rationale for my changes:
>> I did not go into much detail of its working here.
>> A bit detail on this can be to use 'scripts/parse-maintainers
>> --sorted' which produces the sorted file in MAINTAINERS.new by
>> default. The input and output default files can be changed using
>> '--input' and '--output' options. However, here I have omitted these
>> details as running with '--help' option already provides this
>> information in detail.
>> So just making user aware of the script should serve our purpose.
>>
>> What do you think?
>>
> 
> It makes sense not to put that into MAINTAINERS.
> 
> Do you understand how to use ./scripts/parse-maintainers, though?
> 
Yes. From what I have understood, parse-maintainers.pl orders the
maintainers lists in ASCII order.

So, the list for '3C59X NETWORK DRIVER' will be displayed before
'3CR990 NETWORK DRIVER'.

It further orders the entries inside every list in this alphabetical
order: 'MRLSWQBCPTFXNK'.

> So if the warning with checkpatch is shown on a patch, what would you
> need to execute to get a corrected patch?
>

We can directly use this command 'scripts/parse-maintainers.pl
--output="MAINTAINERS" --order' to replace the MAINTAINERS with the
correct order.
However, I wouldn't recommend going for it. This is so because:
1) The MAINTAINERS file at that time might not be ordered properly for
all the different lists in it or among each other. This will result
into producing more numbers of changed lines as desired.

For eg, currently MAINTAINERS is not ordered properly. Running
parse-maintainers.pl on it results in placing 'DELL WMI NOTIFICATIONS
DRIVER' before 'DELL WMI SYSMAN DRIVER' and so on. (producing changes
with 112 Removals and 113 Additions, for simple ordering)

However if we are sure that these misplaced orders should not be
placed in that way, we can add a warning and fix for this too ie for
mutual ASCII ordering of the lists.
But this might need the list to be ordered once, otherwise for any
further changes to MAINTAINERS, it will emit this warning.

The best option currently though might be to use
'scripts/parse-maintainers.pl --order'. This creates a new
MAINTAINERS.new file, without harming our 'MAINTAINERS' file.
Now, one can check if their entries are correct manually and fix it
accordingly.
However, we can maybe automate this (as I think) by:
Read MAINTAINERS.new and store these lists entries as hashes and
replace it somehow (maybe using line numbers) in MAINTAINERS with the
sorted one.

> So if the warning with checkpatch is shown on a patch, what would ou
> you need to execute to get a corrected patch?

Again coming to this question, I don't think we can modify the patch
alone, as the line numbers and other informations in the diff
generated may change drastically. So, I think the user should probably
consider making changes in MAINTAINERS itself and then creating patch.

What do you think?

Thanks
Aditya

> Lukas
> 

_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Re: [Linux-kernel-mentees] [PATCH] Documentation: MAINTAINERS: add information about parse-maintainers.pl

[Lukas Bulwahn]

On Sat, Nov 21, 2020 at 1:59 PM Aditya <yashsri421@gmail.com> wrote:
>
> On 21/11/20 3:27 pm, Lukas Bulwahn wrote:
> > On Fri, Nov 20, 2020 at 11:16 AM Aditya <yashsri421@gmail.com> wrote:
> >>
> >> On 20/11/20 3:42 pm, Aditya Srivastava wrote:
> >>> parse-maintainers.pl is a script which can be used to automatically
> >>> order the contents of MAINTAINERS file in preferred order (i.e.
> >>> 'MRLSWQBCPTFXNK').
> >>>
> >>> But currently we don't have a documentation on it.
> >>>
> >>> Add documentation regarding the same in MAINTAINERS file.
> >>>
> >>> Signed-off-by: Aditya Srivastava <yashsri421@gmail.com>
> >>> ---
> >>> the patch applies perfectly on latest next-20201119
> >>>
> >>>  MAINTAINERS | 3 +++
> >>>  1 file changed, 3 insertions(+)
> >>>
> >>> diff --git a/MAINTAINERS b/MAINTAINERS
> >>> index 5db753fa1295..7ad00af7acd4 100644
> >>> --- a/MAINTAINERS
> >>> +++ b/MAINTAINERS
> >>> @@ -136,6 +136,9 @@ Descriptions of section entries and preferred order
> >>>             printk, pr_info or pr_err
> >>>          One regex pattern per line.  Multiple K: lines acceptable.
> >>>
> >>> +This order can be generated automatically for you using
> >>> +``scripts/parse-maintainers.pl``.
> >>> +
> >>>  Maintainers List
> >>>  ----------------
> >>>
> >>>
> >>
> >> Rationale for my changes:
> >> I did not go into much detail of its working here.
> >> A bit detail on this can be to use 'scripts/parse-maintainers
> >> --sorted' which produces the sorted file in MAINTAINERS.new by
> >> default. The input and output default files can be changed using
> >> '--input' and '--output' options. However, here I have omitted these
> >> details as running with '--help' option already provides this
> >> information in detail.
> >> So just making user aware of the script should serve our purpose.
> >>
> >> What do you think?
> >>
> >
> > It makes sense not to put that into MAINTAINERS.
> >
> > Do you understand how to use ./scripts/parse-maintainers, though?
> >
> Yes. From what I have understood, parse-maintainers.pl orders the
> maintainers lists in ASCII order.
>
> So, the list for '3C59X NETWORK DRIVER' will be displayed before
> '3CR990 NETWORK DRIVER'.
>
> It further orders the entries inside every list in this alphabetical
> order: 'MRLSWQBCPTFXNK'.
>
> > So if the warning with checkpatch is shown on a patch, what would you
> > need to execute to get a corrected patch?
> >
>
> We can directly use this command 'scripts/parse-maintainers.pl
> --output="MAINTAINERS" --order' to replace the MAINTAINERS with the
> correct order.
> However, I wouldn't recommend going for it. This is so because:
> 1) The MAINTAINERS file at that time might not be ordered properly for
> all the different lists in it or among each other. This will result
> into producing more numbers of changed lines as desired.
>
> For eg, currently MAINTAINERS is not ordered properly. Running
> parse-maintainers.pl on it results in placing 'DELL WMI NOTIFICATIONS
> DRIVER' before 'DELL WMI SYSMAN DRIVER' and so on. (producing changes
> with 112 Removals and 113 Additions, for simple ordering)
>
> However if we are sure that these misplaced orders should not be
> placed in that way, we can add a warning and fix for this too ie for
> mutual ASCII ordering of the lists.
> But this might need the list to be ordered once, otherwise for any
> further changes to MAINTAINERS, it will emit this warning.
>
> The best option currently though might be to use
> 'scripts/parse-maintainers.pl --order'. This creates a new
> MAINTAINERS.new file, without harming our 'MAINTAINERS' file.
> Now, one can check if their entries are correct manually and fix it
> accordingly.
> However, we can maybe automate this (as I think) by:
> Read MAINTAINERS.new and store these lists entries as hashes and
> replace it somehow (maybe using line numbers) in MAINTAINERS with the
> sorted one.
>
> > So if the warning with checkpatch is shown on a patch, what would ou
> > you need to execute to get a corrected patch?
>
> Again coming to this question, I don't think we can modify the patch
> alone, as the line numbers and other informations in the diff
> generated may change drastically. So, I think the user should probably
> consider making changes in MAINTAINERS itself and then creating patch.
>
> What do you think?
>

Yes, but we need to provide some help on how to do that... I have no
clue and there is no documentation :)

So, let us assume I create a patch where checkpatch warns I broke MAINTAINERS.

Which steps do I need to do? Can we---for the sake of common
understanding and making the workflow work smoothly---go together the
steps that need to be done?

I guess step 1, you create a quick patch that modifies a MAINTAINERS
section to be wrongly ordered, and send it to me to run checkpatch.pl
and apply it on my latest linux-next tree...

Lukas

> Thanks
> Aditya
>
> > Lukas
> >
>
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

[Linux-kernel-mentees] [PATCH] MAINTAINERS: temporary patch for testing/fixing MAINTAINERS_STYLE

[Aditya Srivastava]

This patch is a testing patch for testing checkpatch.pl with
MAINTAINERS_STYLE warning.

In this patch, a random F entry for 6LOWPAN GENERIC (BTLE/IEEE
802.15.4) is added. Also an M entry is added after F

Signed-off-by: Aditya Srivastava <yashsri421@gmail.com>
---
 MAINTAINERS | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/MAINTAINERS b/MAINTAINERS
index 6aac0f845f34..7937e76f9871 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -178,6 +178,8 @@ S:	Maintained
 F:	Documentation/networking/6lowpan.rst
 F:	include/net/6lowpan.h
 F:	net/6lowpan/
+F:	random/directory
+M:	wrongly/ordered
 
 6PACK NETWORK DRIVER FOR AX.25
 M:	Andreas Koensgen <ajk@comnets.uni-bremen.de>
-- 
2.17.1

_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Re: [Linux-kernel-mentees] [PATCH] MAINTAINERS: temporary patch for testing/fixing MAINTAINERS_STYLE

[Lukas Bulwahn]

On Fri, Dec 4, 2020 at 1:50 PM Aditya Srivastava <yashsri421@gmail.com> wrote:
>
> This patch is a testing patch for testing checkpatch.pl with
> MAINTAINERS_STYLE warning.
>
> In this patch, a random F entry for 6LOWPAN GENERIC (BTLE/IEEE
> 802.15.4) is added. Also an M entry is added after F
>

Okay, what do I need to do next?


> Signed-off-by: Aditya Srivastava <yashsri421@gmail.com>
> ---
>  MAINTAINERS | 2 ++
>  1 file changed, 2 insertions(+)
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 6aac0f845f34..7937e76f9871 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -178,6 +178,8 @@ S:  Maintained
>  F:     Documentation/networking/6lowpan.rst
>  F:     include/net/6lowpan.h
>  F:     net/6lowpan/
> +F:     random/directory
> +M:     wrongly/ordered
>
>  6PACK NETWORK DRIVER FOR AX.25
>  M:     Andreas Koensgen <ajk@comnets.uni-bremen.de>
> --
> 2.17.1
>
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Re: [Linux-kernel-mentees] [PATCH] MAINTAINERS: temporary patch for testing/fixing MAINTAINERS_STYLE

[Aditya]

On 4/12/20 6:23 pm, Lukas Bulwahn wrote:
> On Fri, Dec 4, 2020 at 1:50 PM Aditya Srivastava <yashsri421@gmail.com> wrote:
>>
>> This patch is a testing patch for testing checkpatch.pl with
>> MAINTAINERS_STYLE warning.
>>
>> In this patch, a random F entry for 6LOWPAN GENERIC (BTLE/IEEE
>> 802.15.4) is added. Also an M entry is added after F
>>
> 
> Okay, what do I need to do next?
> 
Now, we can run the command: ./scripts/parse-maintainers.pl --order

This will produce a MAINTAINERS.new file in the root directory, with
ordered entries.
Then, we can lookup our corresponding section in MAINTAINERS.new and
order it correspondingly manually and create the patch again with
corrected changes.

[The new ordered file we get currently has a lot of changes when
compared with MAINTAINERS. This is so because there are other sections
and entries which need ordering as well. This is the reason, we cannot
directly replace MAINTAINERS with MAINTAINERS.new (as this might
produce more changes than desired for that patch); rather just fix our
modified lines]

> 
>> Signed-off-by: Aditya Srivastava <yashsri421@gmail.com>
>> ---
>>  MAINTAINERS | 2 ++
>>  1 file changed, 2 insertions(+)
>>
>> diff --git a/MAINTAINERS b/MAINTAINERS
>> index 6aac0f845f34..7937e76f9871 100644
>> --- a/MAINTAINERS
>> +++ b/MAINTAINERS
>> @@ -178,6 +178,8 @@ S:  Maintained
>>  F:     Documentation/networking/6lowpan.rst
>>  F:     include/net/6lowpan.h
>>  F:     net/6lowpan/
>> +F:     random/directory
>> +M:     wrongly/ordered
>>
>>  6PACK NETWORK DRIVER FOR AX.25
>>  M:     Andreas Koensgen <ajk@comnets.uni-bremen.de>
>> --
>> 2.17.1
>>

_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees