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
