Message-ID: <CAKXUXMypvMeiRGCXbX2ogJQ4KDBc6v-s7cH4t8Tk9=5NerBN1w@mail.gmail.com>
Date: Tue, 5 Mar 2024 13:39:23 +0100
From: Lukas Bulwahn <lukas.bulwahn@...il.com>
To: Jonathan Corbet <corbet@....net>
Cc: workflows@...r.kernel.org, linux-doc@...r.kernel.org, 
	kernel-janitors@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH 0/3] Towards a re-organized submitting patches

On Sun, Mar 3, 2024 at 5:31 PM Jonathan Corbet <corbet@....net> wrote:
>
> Lukas Bulwahn <lukas.bulwahn@...il.com> writes:
>
> > Dear Jonathan,
> >
> > I wanted to clean up the development-process documentation. There is
> > however no easy way to break the ice here:
> >
> > The elephant in the room is that there is some unclear relation between
> > 5.Posting.rst, 6.Followthrough.rst and submitting-patches.rst.
> > (Yes, I know each document has its own history...; but let us put the
> > history aside for now.)
>
> FWIW, the objective of those two documents is quite different; one is a
> high-level overview of how the development process as a whole works, the
> other is a detailed guide to submitting work for consideration.
>

Yes, that _objective_ is clear when reading the documents.
However, unfortunately, the detailed guide to submitting work for
consideration in submitting-patches.rst really is not that much more
detailed than what 5.Posting and 6.Followthrough already recommend.
A lot of the "details" in submitting-patches.rst is then also just
details on topics that are much more an explanation than actual
recommendation for specific actions.

Let me clean things up in submitting-patches, and then start a proper
comparison.

> > Submitting-patches.rst contains information largely put together from
> > different initial starting points and is partly outdated due to common
> > workflows with git format-patch and git send-email.
>
> You should have seen it before I thrashed it a few years back :)
>
> > For a simple experiment, I moved the larger parts on the tags
> > (signed-off-by, co-developed-by, acked-by, reported-by, etc.) into a
> > separate document and then ran the numbers on submitting-patches again:
> >
> >   4329 submitting-patches.rst
> >
> > Nowt, the size of submitting-patches is actually below Posting and
> > Followthrough.
>
> I don't think we should be driven by word counts.  I do think that
> moving a bunch of information on tags to its own document could make
> sense.
>
> > So, the difficult task to reach a coherent process description is to see
> > some relation between these documents and then go through the editorial
> > changes. I have come up with this kind of vision:
> >
> > Phase 1: Clean up submitting patches
> >
> >   Topics/Statements that can be easily cleaned up first do not get in
> >   the way (at least mentally) when trying to understand the next steps.
> >
> >   E.g., as an experiment I moved the details on tags into a separate
> >   document.
>
> Fine.
>
> > Phase 2: Make submitting-patches have one clear temporal flow.
> >
> >   The top-level structure should basically be along the temporal order of
> >   things: Prepare a patch, Post a patch, Respond to review, Send reworked
> >   patches, Be patient before resending
>
> This makes sense as well.  I wonder if splitting the document along some
> of those lines might also be a good idea, with submitting-patches.rst
> becoming a relatively short overview deferring details to the others.
> This is one of the most important docs we have, and it's far too much
> for people to engage with all at once.
>

I understand that people nowadays do not read prose from top to
bottom, as soon as it exceeds a certain length. So, for sure, we can
consider splitting the current content into multiple pieces and add
links between them. However, I also want to avoid that we have say 15
documents of a hundred lines, and you are always jumping
back-and-forth in your web browser while reading. I think the split is
going to be into two or three documents if at all.

I will do some experiments and suggest some splitting.

> > Phase 3: Merge the pieces of content from Posting and Followthrough into
> > submitting patches if it adds something to that document.
> >
> >   When both documents roughly cover the topics of similar depth, we look
> >   fine-grained into how to construct the one document that has the best
> >   from both documents.
> >
> > Phase 4: Remove Posting and Followthrough and simply replace it in the
> > process description with submitting patches.
>
> In broad terms, this seems like a good direction to me.
>
> Again, let's remember the different purposes of these documents.  The
> development-process document is an overall description of the process,
> so it doesn't need the details.  But when you say:
>
> > Posting will not be missed.
>
> I don't entirely agree.  But I don't doubt it could be a fraction of
> what it is now.
>

When I say "Posting will not be missed", I mean the name
"5.Posting.rst" will not be missed, as the future submitting-patches,
partially existent on my hard disk right now, includes the best of
5.Posting.rst as it is now, namely the natural flow of the
explanation, the good style of writing, being precise and concise and
the ability to address all audiences with a suitable text, e.g.,
newcomers and experienced kernel developers enjoy reading it. Some
important information in 5.Posting.rst should really also be mentioned
in submitting-patches.rst.

I think if submitting-patches.rst is structured and written well, the
development process description can go from 4. Getting the code right
to "5.Submitting patches" and the readers would not even notice that
they once originated from very different sources and authors.

> > So, here are some first changes to Phase 1 and Phase 2.
>
> At a first glance, these changes seem fine.  I think I'll hold them
> until after the merge window so that others can think about what you're
> up to, but I suspect there will be no reason not to apply this first set
> then.
>
> Thanks for working on this material; it's some of the most important we
> have and it definitely needs some attention.
>

I will continue working on it and see what I consider stable enough in
moving around that it deserves to be posted to the mailing list. While
working on the document, it is unfortunately a lot of temporary
movement back and forth, or huge changes at once and it is a bit
difficult to then extract the next natural change to propose, but I
will see how I can present this best piece by piece.


Lukas

Powered by blists - more mailing lists