mbox series

[v2,0/3] docs: submit-checklist: structure by category

Message ID 20240229030743.9125-1-lukas.bulwahn@gmail.com
Headers
Series docs: submit-checklist: structure by category |

Message

Lukas Bulwahn Feb. 29, 2024, 3:07 a.m. UTC 
  Dear Jonathan,

this v2 series addresses all review feedback of the patch v1 here:

  https://lore.kernel.org/linux-doc/20240226104653.54877-1-lukas.bulwahn@gmail.com/

Immediate actionable review feedback was:

from Jani Nikula:
  - turn categories into subheadings
  - use common heading adornment
  - change to bullet or autonumbered lists
  - propose those changes as separate additional patches

from Randy Dunlap:
  - if subheadings, drop the colons at the end.
  - acked change to test with linux-next
  - Stephen Rothwell requested item 1 to stay item 1.
  - pointed out swapping the config names in the commit message.

v1 -> v2:
The commit message of patch 1/3 is improved addressing Randy's
feedback on the commit message.
The diff itself of patch 1/3 is unchanged.

Patch 2/3 and 3/3 addresses Jani's and Randy's feedback.

The extended discussion and feedback was:

  - Is the checkstack script worth mentioning or can it be replaced?
  - missing some nowadays more important points.
  - consider getting it coherent with submitting-patches.rst

I have put the extended feedback onto my todo list; for the next
iteration on this document---after cleaning up submitting-patches and
making the howto and submitting-patches more coherent.

I followed Jani's request and created three patches, this might help
in the next/final review---if any further review happens now.

However, I do not think the kernel repository needs to be swamped with
three patches for this 'logically one change' to a single document. So,
I also squashed the three patches back into one patch, sent out as
PATCH v2-squashed:

  https://lore.kernel.org/linux-doc/20240229030146.8418-1-lukas.bulwahn@gmail.com/

Please either pick this patch series or just the PATCH v2-squashed as
you see fit.

Lukas Bulwahn (3):
  docs: submit-checklist: structure by category
  docs: submit-checklist: use subheadings
  docs: submit-checklist: change to autonumbered lists

 Documentation/process/submit-checklist.rst | 163 +++++++++++----------
 1 file changed, 88 insertions(+), 75 deletions(-)

Comments

Jani Nikula Feb. 29, 2024, 10:25 a.m. UTC | #1 
On Thu, 29 Feb 2024, Lukas Bulwahn <lukas.bulwahn@gmail.com> wrote:
> from Jani Nikula:
>   - turn categories into subheadings
>   - use common heading adornment
>   - change to bullet or autonumbered lists
>   - propose those changes as separate additional patches

I was hoping these cleanups would've come *first*, but up to Jon to
decide if that really matters.

BR,
Jani.
Lukas Bulwahn Feb. 29, 2024, 10:36 a.m. UTC | #2 
On Thu, Feb 29, 2024 at 11:25 AM Jani Nikula <jani.nikula@intel.com> wrote:
>
> On Thu, 29 Feb 2024, Lukas Bulwahn <lukas.bulwahn@gmail.com> wrote:
> > from Jani Nikula:
> >   - turn categories into subheadings
> >   - use common heading adornment
> >   - change to bullet or autonumbered lists
> >   - propose those changes as separate additional patches
>
> I was hoping these cleanups would've come *first*, but up to Jon to
> decide if that really matters.
>

I see, changing to autonumbered lists could be done before, but the
subheadings only exist once reordered.

I am still in favor of the squashed commit: we are talking about a
very small document that central content has not been touched for a
long time. It is not code, where someone would bisect into. So, the
history does not need to carry every single stylistic change as yet
another commit.

Jani, I can do what you are asking for---but it is certainly going to
take yet a few hours to have the commits exactly into that form of
stylistic changes.

Let us see what Jon thinks.

Lukas
Jonathan Corbet March 3, 2024, 4 p.m. UTC | #3 
Lukas Bulwahn <lukas.bulwahn@gmail.com> writes:

> Dear Jonathan,
>
> this v2 series addresses all review feedback of the patch v1 here:
>
>   https://lore.kernel.org/linux-doc/20240226104653.54877-1-lukas.bulwahn@gmail.com/
>
> Immediate actionable review feedback was:
>
> from Jani Nikula:
>   - turn categories into subheadings
>   - use common heading adornment
>   - change to bullet or autonumbered lists
>   - propose those changes as separate additional patches
>
> from Randy Dunlap:
>   - if subheadings, drop the colons at the end.
>   - acked change to test with linux-next
>   - Stephen Rothwell requested item 1 to stay item 1.
>   - pointed out swapping the config names in the commit message.
>
> v1 -> v2:
> The commit message of patch 1/3 is improved addressing Randy's
> feedback on the commit message.
> The diff itself of patch 1/3 is unchanged.
>
> Patch 2/3 and 3/3 addresses Jani's and Randy's feedback.
>
> The extended discussion and feedback was:
>
>   - Is the checkstack script worth mentioning or can it be replaced?
>   - missing some nowadays more important points.
>   - consider getting it coherent with submitting-patches.rst
>
> I have put the extended feedback onto my todo list; for the next
> iteration on this document---after cleaning up submitting-patches and
> making the howto and submitting-patches more coherent.
>
> I followed Jani's request and created three patches, this might help
> in the next/final review---if any further review happens now.
>
> However, I do not think the kernel repository needs to be swamped with
> three patches for this 'logically one change' to a single document. So,
> I also squashed the three patches back into one patch, sent out as
> PATCH v2-squashed:
>
>   https://lore.kernel.org/linux-doc/20240229030146.8418-1-lukas.bulwahn@gmail.com/
>
> Please either pick this patch series or just the PATCH v2-squashed as
> you see fit.
>
> Lukas Bulwahn (3):
>   docs: submit-checklist: structure by category
>   docs: submit-checklist: use subheadings
>   docs: submit-checklist: change to autonumbered lists
>
>  Documentation/process/submit-checklist.rst | 163 +++++++++++----------
>  1 file changed, 88 insertions(+), 75 deletions(-)

So I've applied the first two patches, since there doesn't seem to be
any disagreement over those.  Once we figure out how we want the
autonumbering to be done, that can go in as well.

Thanks,

jon