From: Kristoffer Haugsbakk Date: Mon, 13 Oct 2025 16:42:28 GMT Subject: Re: [PATCH] doc: patch-id: convert to the modern synopsis style Message-ID: In-Reply-To: On Fri, Oct 10, 2025, at 10:50, Junio C Hamano wrote: >> This is part one of a multi-series effort focusing on this >> documentation page. Technically that intent started with topic >> kh/doc-patch-id-markup-fix, but I published that before I learned >> about the idea presented in . >> So this gets named “part one” in the cover letter (and maybe on the >> topic name). >> >> The current plan for parts 2–5: >> >> 2. Various smaller fixups (many small patches/commits) >> 3. Mention the two config variables in git-config(1) >> 4. Make it more clear that you can feed multiple diffs to this command >> 5. An “Examples” section > > Quite honestly, this smells like making a mountain out of a > molehill. Got it. > 5-patch topic that focuses on improving a single > documentation page is nothing unusual, but it is very unusual and > awkward to handle for a topic that focuses on improving a single > documentation page is spread across 5 separate topics, each building > on top of the previous one. To be sure: I’ll abort the plan if it turns out to be worse for the reviewers. I can make the following amemdment right now: after this current topic I will wait until it graduates to `master` instead of basing the next topic on the merge to `next`. Either that or everything that I plan to send gets sent in the next topic. > >> Why a multi-part series? It started with the idea of (1) emphasizing >> that this command can take multiple patches, and (2) making an >> Examples. But then I saw other things to fix. And they ought to go >> first... eventually I ended up with many commits or ideas. > > Perhaps then after you built up the final shape, you'd need time to > ruminate over it and possibly reorganize to find the best order and > organization to present it as a N-patch single series? Typically, a > collection of thoughts presented in the order they came to one's mind > is much harder to judge, relative to an effort to tell a coherent story > that moves to a goal. That’s a good point. I will rather scrap things and recreate them if I come up with a better order rather than committing to the existing one.