On Sun, Mar 3, 2024 at 5:31 PM Jonathan Corbet <corbet@xxxxxxx> wrote: > > Lukas Bulwahn <lukas.bulwahn@xxxxxxxxx> 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
