Re: [PATCH v2] Documentation: process: Correct numbering

[Randy Dunlap]

On 12/22/20 9:11 AM, Lukas Bulwahn wrote:
> On Tue, Dec 22, 2020 at 5:36 PM Randy Dunlap <rdunlap@xxxxxxxxxxxxx> wrote:
>>
>> On 12/22/20 8:23 AM, Lukas Bulwahn wrote:
>>> On Mon, Dec 21, 2020 at 5:52 PM Jonathan Corbet <corbet@xxxxxxx> wrote:
>>>>
>>>> On Tue, 15 Dec 2020 20:42:36 +0000
>>>> Milan Lakhani <milan.lakhani@xxxxxxxxxxxxxxx> wrote:
>>>>
>>>>> Renumber the steps in submit-checklist.rst as some numbers were skipped.
>>>>>
>>>>> Fixes: 72deb455b5ec ("block: remove CONFIG_LBDAF")
>>>>> Signed-off-by: Milan Lakhani <milan.lakhani@xxxxxxxxxxxxxxx>
>>>>> ---
>>>>>  Documentation/process/submit-checklist.rst | 24 ++++++++++++------------
>>>>>  1 file changed, 12 insertions(+), 12 deletions(-)
>>>>>
>>>>> diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst
>>>>> index 1879f88..230ee42 100644
>>>>> --- a/Documentation/process/submit-checklist.rst
>>>>> +++ b/Documentation/process/submit-checklist.rst
>>>>> @@ -75,44 +75,44 @@ and elsewhere regarding submitting Linux kernel patches.
>>>>>  13) Has been build- and runtime tested with and without ``CONFIG_SMP`` and
>>>>>      ``CONFIG_PREEMPT.``
>>>>>
>>>>> -16) All codepaths have been exercised with all lockdep features enabled.
>>>>> +14) All codepaths have been exercised with all lockdep features enabled.
>>>>>
>>>>> -17) All new ``/proc`` entries are documented under ``Documentation/``
>>>>> +15) All new ``/proc`` entries are documented under ``Documentation/``
>>>> [...]
>>>>
>>>> I've applied this, but, if you're going to stick a "Fixes" tag onto a
>>>> patch, it's probably only polite to copy the original author.  I'm not
>>>> fully convinced that the tag is warranted in this case.
>>>>
>>>> This document seems out of date in a number of ways; it could really use a
>>>> rather more thorough updating than this.
>>>>
>>>
>>> Jon, I completely agree on your out-of-date comment. That is why we
>>> pointed Milan to that checklist to start with some small basic changes
>>> and continue with increasingly more challenging and complex updates.
>>>
>>> Milan, next update for you to consider: what does "make headers_check"
>>> do nowadays? (spoiler alert: it does nothing) Adjust the documentation
>>> for that.
>>>
>>> Then, a more general improvement: think about structuring the
>>> checklist to follow the structure of the other submission guidelines.
>>> So, reorder the current checklist and check if the step is mentioned
>>> in submitting-patches and where and make the checklist much more
>>> aligned to submitting-patches.
>>
>> Please do not move item #1. It is #1 for a reason.
>>
> 
> Randy, thanks for your hint.
> 
> We will consider that. I never considered this list ordered by
> priority but maybe somebody did really consider it with those
> priorities. To me, it seemed rather randomly sorted (with some
> duplicates) or somehow sorted by the various topics a patch might
> touch (e.g., some rules on Kconfig, then some rules for device
> drivers, then some on documenting APIs, then some on testing options).

Probably only rule #1 is sorted.  :)

> Interestingly, I could not find any mention of checklist item #1 in
> development-process.rst and further linked pages, despite it being
> very explicit on various other points.
> 
> Just for the record on my investigation, it is also not mentioned in
> submitting-patches, which I did not expect, though, because that guide
> touches more on the specific stage of preparing a submission than on
> the creation of a code change.
> 
> So, if item #1 is so important to the development process, it might
> deserve to be mentioned elsewhere with some explanation as well.
> 
> Side remark: I am also wondering if a clang-tidy check could actually
> check that property of proper includes with a quick rule; that would
> be a nice showcase for clang-tidy if that can be implemented quickly.

That would be great.

> Milan, you see there is quite some potential work here.
> 
> Milan, maybe you can find some good way of structuring the checklist
> and make sure that #1 is still clear to be most important.
> 
> I am happy to assist you, Milan, on improving this checklist.


thanks.
-- 
~Randy