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