Message-ID: <20240301134637.27880-1-lukas.bulwahn@gmail.com>
Date: Fri,  1 Mar 2024 14:46:34 +0100
From: Lukas Bulwahn <lukas.bulwahn@...il.com>
To: Jonathan Corbet <corbet@....net>,
	workflows@...r.kernel.org,
	linux-doc@...r.kernel.org
Cc: kernel-janitors@...r.kernel.org,
	linux-kernel@...r.kernel.org,
	Lukas Bulwahn <lukas.bulwahn@...il.com>
Subject: [PATCH 0/3] Towards a re-organized submitting patches

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.)

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.

Often when new additions are made, they are somehow added to both
documents with slightly different wording.

Also, looking at the word count (with wc -l) on next-20240227:

  2917 5.Posting.rst
  2136 6.Followthrough.rst
  5878 submitting-patches.rst

So, from the numbers, you would expect that submitting-patches.rst is a
detailing of Posting and Followthrough.
However, it is really difficult to see how submitting-patches.rst would
be a refinement of Posting and Followthrough or if and where it is not.
First, at the moment, the different initial starting points and different
ordering somehow makes it difficult to judge.

Also, the factor of 20% more words really does not indicate much more
content in submitting-patches compared to Posting and Followthrough.

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.

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.
  
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

  "No MIME, no links, no compression, no attachments. Just plain text"
  needs to be reworked into "Send your patch".
  
  The content from the canonical patch format needs to evaluated on
  relevance with a git workflow and the important pieces need to be
  included into the temporal flow.

  In other words, it is worth describing "the canonical patch format" much
  more from what the submitter may add where and in which format rather
  than explaining the purpose of some things that git format-patch does by
  default and usually nobody would play around with.

  Probably, prepare a patch will need to be broken down a bit in some
  smaller steps. The "Send reworked patch" section is new and needs to
  include content distributed throughout submitting-patches.
  
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 some way, when both documents cover the topic in similar depth either
  document could be deleted.
  However, the name "submitting patches" is probably already stuck too much
  with the community; I have seen many presentations referring to
  submitting patches, but I have not seen anyone referring to '5.Posting'
  in any presentation.

  Also, the number of references---excluding translations---to Posting and
  Followthrough, submitting_patches.rst is 3, 1 and 41, respectively.
  In fact, the two references in handling-regressions mention Posting just
  as further reference next to submitting patches, clearly just indicating
  this kind of duplication. So, submitting-patches is much more stuck with
  the community at the current state and once the content from Posting is
  added to submitting-patches, Posting will not be missed.

  Further, this requires to rewrite the process description intro
  and the intro of submitting patches a bit, such that if readers:

  - just jump into submitting-patches from the top page,
  - or are going through the development-process from cover to cover
    (coming from its section 4 and moving on to section 7)

  they see a roughly consistent flow of thought and suitable introduction.
  But I think this should be feasible.

Let us see how long it takes me to work through this and convince the
reviewers and future readers that we are moving a good direction.

So, here are some first changes to Phase 1 and Phase 2.

Current state:

I spend roughly two days of work---besides the usual distractions---on
this topic, digging into the documents and trying to make a plan.

Obviously, the final goal is not reached with this series, but I would
like to get first feedback and hope that we can get the first patches
generally accepted (but not necessarily included into the repository yet
if only truly accepted when seeing the full picture of changes) to
continue the rework with some backing confidence that this is not all in
vain.

Please let me know if this is going in the right direction and if some
patches would already be accepted to be included upfront to lower the
risks and conflicts when continuing the editorial work.

Well, long text... some short simple patches for now.


Best regards,

Lukas


Lukas Bulwahn (3):
  docs: submitting-patches: divert focus from PATCH in the subject line
  docs: submitting-patches: move split_changes before describe_change
  docs: submitting-patches: move backtraces to patch description

 Documentation/process/submitting-patches.rst | 119 +++++++++----------
 1 file changed, 58 insertions(+), 61 deletions(-)

-- 
2.43.2

Powered by blists - more mailing lists