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

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 10, 2025, 08:50 UTC
Message-ID: <xmqqcy6vb0nw.fsf@gitster.g>
In-Reply-To: <978261e3be4.1760043036.git.code@khaugsbakk.name>

kristofferhaugsbakk@fastmail.com writes:

Show 5 quoted lines

>     This depends on the topic kh/doc-patch-id-markup-fix (39969438 (doc:
>     patch-id: fix accidental literal blocks, 2025-09-29) merged into
>     v2.50.0 (because that’s what the topic is based on).
>     
>     (is there a “reference” convention for mentioning a topic + commit?)

The above is perfectly understandable.

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

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

But we'll see.