Re: [PATCH] doc: patch-id: convert to the modern synopsis style

From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Date: Oct 13, 2025, 16:42 UTC
Message-ID: <ccbaa98e-7223-4c75-9844-f0025de9f84c@app.fastmail.com>
In-Reply-To: <xmqqcy6vb0nw.fsf@gitster.g>

On Fri, Oct 10, 2025, at 10:50, Junio C Hamano wrote:

Show 16 quoted lines

>>     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 <cover.1759873165.git.me@ttaylorr.com>.
>>     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.

Show 5 quoted lines

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

Show 12 quoted lines

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