Adding doc for parse-maintainers.pl

Linux-kernel-mentees In review Aditya 2 participants 11 messages Nov 18, 2020 – Dec 4, 2020

Share & tools

Aditya

author

2020-11-18 18:02 UTC #0 lore raw

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
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Lukas Bulwahn

2020-11-18 19:12 UTC #1 lore raw

Quoted 11 lines · 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:

Quoted 9 lines

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

Quoted 4 lines

--
Thanks
Aditya

_______________________________________________
Linux-kernel-mentees mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Lukas Bulwahn

2020-11-19 08:15 UTC #2 lore raw

Quoted 12 lines · Lukas Bulwahn

Quoted 8 lines · 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

Quoted 5 lines

Quoted 5 lines
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.

Quoted 5 lines

Quoted 5 lines
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

Quoted 13 lines

Quoted 1 line
What do you think/suggest?
That is good.
We can more documentation on parse-maintainers in a new separate page.
Lukas
Quoted 4 lines
--
Thanks
Aditya

_______________________________________________
Linux-kernel-mentees mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Aditya Srivastava

author

2020-11-20 10:13 UTC #3 lore raw

PATCH 1/1 Documentation: MAINTAINERS: add information about parse-maintainers.pl

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 <[email protected]>

---
the patch applies perfectly on latest next-20201119

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

MAINTAINERS +3 -0

index 5db753fa1295..7ad00af7acd4 100644
@@ -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
 ----------------

Signature · 6 lines

2.17.1

_______________________________________________
Linux-kernel-mentees mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Aditya

author

2020-11-20 10:16 UTC #4 lore raw

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

Quoted 21 lines · 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 <[email protected]>
---
the patch applies perfectly on latest next-20201119
 MAINTAINERS | 3 +++
 1 file changed, 3 insertions(+)
MAINTAINERS +0 -0
index 5db753fa1295..7ad00af7acd4 100644

MAINTAINERS Descriptions of section entries and preferred order · line 144

Quoted 9 lines

MAINTAINERS +3 -0

@@ -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
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Lukas Bulwahn

2020-11-21 09:57 UTC #5 lore raw

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

Quoted 43 lines · Aditya

Quoted 21 lines · 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 <[email protected]>
---
the patch applies perfectly on latest next-20201119
 MAINTAINERS | 3 +++
 1 file changed, 3 insertions(+)
MAINTAINERS +0 -0
index 5db753fa1295..7ad00af7acd4 100644
MAINTAINERS Descriptions of section entries and preferred order · line 144
Quoted 9 lines
MAINTAINERS +3 -0
@@ -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.

Quoted 2 lines

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
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Aditya

author

2020-11-21 12:59 UTC #6 lore raw

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

Quoted 44 lines · Lukas Bulwahn

Quoted 43 lines · Aditya
Quoted 21 lines · 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 <[email protected]>
---
the patch applies perfectly on latest next-20201119
 MAINTAINERS | 3 +++
 1 file changed, 3 insertions(+)
MAINTAINERS +0 -0
index 5db753fa1295..7ad00af7acd4 100644
MAINTAINERS Descriptions of section entries and preferred order · line 144
Quoted 9 lines
MAINTAINERS +3 -0
@@ -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.

Quoted 7 lines

Quoted 2 lines
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'.

Quoted 3 lines

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.

Quoted 2 lines

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

Quoted 2 lines

Lukas

_______________________________________________
Linux-kernel-mentees mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Lukas Bulwahn

2020-12-04 10:22 UTC #7 lore raw

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

Quoted 98 lines · Aditya

Quoted 44 lines · Lukas Bulwahn
Quoted 43 lines · Aditya
Quoted 21 lines · 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 <[email protected]>
---
the patch applies perfectly on latest next-20201119
 MAINTAINERS | 3 +++
 1 file changed, 3 insertions(+)
MAINTAINERS +0 -0
index 5db753fa1295..7ad00af7acd4 100644
MAINTAINERS Descriptions of section entries and preferred order · line 144
Quoted 9 lines
MAINTAINERS +3 -0
@@ -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.
Quoted 7 lines
Quoted 2 lines
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'.
Quoted 3 lines
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.
Quoted 2 lines
So if the warning with checkpatch is shown on a patch, what would ou you need to execute to get a corrected patch?

Quoted 7 lines

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

Quoted 6 lines

Thanks
Aditya
Quoted 2 lines
Lukas

_______________________________________________
Linux-kernel-mentees mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Aditya Srivastava

author

2020-12-04 12:50 UTC #8 lore raw

PATCH 1/1 MAINTAINERS: temporary patch for testing/fixing MAINTAINERS_STYLE

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 <[email protected]>

---
 MAINTAINERS | 2 ++
 1 file changed, 2 insertions(+)

MAINTAINERS +2 -0

index 6aac0f845f34..7937e76f9871 100644
@@ -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 <[email protected]>

Signature · 6 lines

2.17.1

_______________________________________________
Linux-kernel-mentees mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Lukas Bulwahn

2020-12-04 12:53 UTC #9 lore raw

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

Quoted 7 lines · 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

Okay, what do I need to do next?

Quoted 19 lines

Signed-off-by Aditya Srivastava <[email protected]>

---
 MAINTAINERS | 2 ++
 1 file changed, 2 insertions(+)

MAINTAINERS +2 -1

index 6aac0f845f34..7937e76f9871 100644
@@ -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 <[email protected]>
--

Quoted 2 lines

2.17.1

_______________________________________________
Linux-kernel-mentees mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Aditya

author

2020-12-04 13:05 UTC #10 lore raw

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

Quoted 11 lines · Lukas Bulwahn

Quoted 7 lines · 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
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]

Quoted 17 lines

Signed-off-by Aditya Srivastava <[email protected]>

---
 MAINTAINERS | 2 ++
 1 file changed, 2 insertions(+)

MAINTAINERS +2 -0

index 6aac0f845f34..7937e76f9871 100644
@@ -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

Quoted 5 lines

MAINTAINERS +0 -1

 6PACK NETWORK DRIVER FOR AX.25
 M:     Andreas Koensgen <[email protected]>
--

2.17.1

_______________________________________________
Linux-kernel-mentees mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees