From: Junio C Hamano <gitster@pobox.com>
To: Okhuomon Ajayi <okhuomonajayi54@gmail.com>
Cc: git@vger.kernel.org
Subject: Re: [PATCH v3] doc: wrap emailed text to a maximum of 72 columns
Date: Fri, 20 Nov 2026 09:58:54 -0800 [thread overview]
Message-ID: <xmqqmrr3qt9d.fsf@gitster.g> (raw)
In-Reply-To: <20261120110215.42209-1-okhuomonajayi54@gmail.com> (Okhuomon Ajayi's message of "Fri, 20 Nov 2026 12:02:15 +0100")
Okhuomon Ajayi <okhuomonajayi54@gmail.com> writes:
> CodingGuidelines, SubmittingPatches, and ReviewingGuidelines do
> not say how long an emailed line should be.
This initial observation of the status quo is given clearly, which
makes an easy introduction for readers to the issue you are
addressing.
> State the limit in
> each: wrap the text to a maximum of 72 columns, matching the
> commit message convention, so it still fits on an 80-column
> terminal after a few levels of quoting.
The above says what we do and why we do so. In a proposed log
message, the latter is more important.
> Leave a blank line
> between paragraphs. A block of quoted text counts as a paragraph.
Contrasted with the above, this lacks the "why", and is written with
a funny verb. "State the limit..." was an instruction to the
imaginary person who is making the change to our sources, which is
the "imperative mood" convention our SubmittingPatches specifies.
But "Leave a blank line" is an instruction that the imaginary person
is adding. You need to tell that person to tell our readers to do
so. Something like
Tell readers to leave a blank line between paragraphs.
In order to properly give the "why", we'd need to go back to the
initial observation and say that these three documents do not say
that there should be paragraph breaks for readability.
Side note: if your convention is "each single long line is a
paragraph", then there is no need for a paragraph break. That
seems to be the common format LLMs produce.
But our convention is "lines in a paragraph are limited to a
comfortable length of 72 columns, and the beginning of a new
paragraph is signaled by a blank line". In other words, line
length limits and paragraph breaks go hand in hand.
> + - E-mailed text, including a patch message and a review reply, is
> + wrapped to a maximum of 72 columns, matching the commit message
The phrase "patch message" is not used elsewhere in Documentation/.
We use phrases like "log message", "commit message", and "cover
letter". We do not want to use the word "patch" here to avoid
giving a misleading hint to line-wrap diff lines in a patch ;-)
- E-mailed text intended for human-to-human communication, like
log messages, explanations in cover letters, review comments
and their responses, is wrapped to ...
> diff --git a/Documentation/ReviewingGuidelines.adoc b/Documentation/ReviewingGuidelines.adoc
>
> +- Wrap a review reply to a maximum of 72 columns, matching the commit
> + message convention, so it still fits on an 80-column terminal after
> + being quoted a few times. Leave a blank line between paragraphs. A
> + block of quoted text counts as a paragraph, so leave a blank line
> + before and after it.
"before and after it, too."? I personally do not see a need to
specifically say ">" quoted text and what you write in response
to that quoted part are different paragraph, but some people may
need to be told, I guess.
Thanks.
prev parent reply other threads:[~2026-11-20 17:58 UTC|newest]
Thread overview: 8+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-19 10:53 [PATCH] doc: wrap emailed text near 70 columns Okhuomon Ajayi
2026-11-19 22:20 ` Junio C Hamano
2026-11-19 22:26 ` Okhuomon Ajayi
2026-11-20 5:59 ` [PATCH v2] " Okhuomon Ajayi
2026-11-20 10:07 ` Andy Koppe
2026-11-20 10:26 ` Okhuomon Ajayi
2026-11-20 11:02 ` [PATCH v3] doc: wrap emailed text to a maximum of 72 columns Okhuomon Ajayi
2026-11-20 17:58 ` Junio C Hamano [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqqmrr3qt9d.fsf@gitster.g \
--to=gitster@pobox.com \
--cc=git@vger.kernel.org \
--cc=okhuomonajayi54@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox