git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: Jeff King <peff@peff.net>
To: Johannes Schindelin <Johannes.Schindelin@gmx.de>
Cc: Junio C Hamano <gitster@pobox.com>,
	Johannes Schindelin via GitGitGadget <gitgitgadget@gmail.com>,
	git@vger.kernel.org
Subject: Re: [PATCH 0/1] Drop last MakeMaker reference
Date: Mon, 11 Mar 2019 16:24:41 -0400	[thread overview]
Message-ID: <20190311202441.GB18263@sigill.intra.peff.net> (raw)
In-Reply-To: <nycvar.QRO.7.76.6.1903081718330.41@tvgsbejvaqbjf.bet>

On Fri, Mar 08, 2019 at 05:27:36PM +0100, Johannes Schindelin wrote:

> > Or perhaps GGG can learn to avoid 0/1 for a single-patch topic ;-)
> 
> It is easier, and more consistent, to have a cover letter even then, for
> things like the broader explanation of the context, the changes since the
> previous iteration, and the range-diff (which would make v2, v3, v4, etc
> utterly unreadable from my point of view if they were integrated into the
> single patches, as I used to do with interdiffs).

Just my two cents:

As a reviewer, I generally prefer not to see a separate cover letter for
a single patch. At least for the first version (I agree it gets unwieldy
showing a range-diff after the "---" for subsequent versions, unless it
happens to be pretty short).

My reasoning is that I've noticed that many of the GGG-sent patches
often end up duplicating quite a bit of content between the cover letter
and the commit message of the patch (or worse, putting things only in
the cover letter that really could go into the commit message). That
doubles the time I spend reading and understanding the patch's rationale
(and I'm speaking subjectively here, of course; I didn't measure it).

I don't think it's an _inherent_ problem with a separate cover letter.
But something about the workflow causes people to write up over-long
cover letters. Which presumably is the fact that they're presented with
a PR textbox to write the rationale separately from when they wrote the
commit message. So they err on the side of repeating themselves, and
never see the two pieces "together" (like the reader will), which makes
the redundancy more obvious.

I'd say 99% of the time a single-patch doesn't need any cover letter
material at all. And even a multi-patch series really just needs a tl;dr
of the problem and a sketch of the solution. In both cases, the commit
messages should carry the meat.

(That's all specific to our project, of course; I know many projects
don't care about commit messages at all and expect PR descriptions to be
the first-class explanations).

-Peff

      reply	other threads:[~2019-03-11 20:24 UTC|newest]

Thread overview: 9+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-02-25 19:27 Johannes Schindelin via GitGitGadget
2019-02-25 19:27 ` [PATCH 1/1] mingw: drop " Johannes Schindelin via GitGitGadget
2019-02-25 20:02   ` Jonathan Nieder
2019-02-25 22:07     ` Johannes Schindelin
2019-03-03  1:19 ` [PATCH 0/1] Drop last " Junio C Hamano
2019-03-07 10:10   ` Johannes Schindelin
2019-03-08  1:41     ` Junio C Hamano
2019-03-08 16:27       ` Johannes Schindelin
2019-03-11 20:24         ` Jeff King [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

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20190311202441.GB18263@sigill.intra.peff.net \
    --to=peff@peff.net \
    --cc=Johannes.Schindelin@gmx.de \
    --cc=git@vger.kernel.org \
    --cc=gitgitgadget@gmail.com \
    --cc=gitster@pobox.com \
    --subject='Re: [PATCH 0/1] Drop last MakeMaker reference' \
    /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

git@vger.kernel.org list mirror (unofficial, one of many)

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 git git/ https://public-inbox.org/git \
		git@vger.kernel.org
	public-inbox-index git

Example config snippet for mirrors.
Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/inbox.comp.version-control.git
	nntp://ie5yzdi7fg72h7s4sdcztq5evakq23rdt33mfyfcddc5u3ndnw24ogqd.onion/inbox.comp.version-control.git
	nntp://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/inbox.comp.version-control.git
	nntp://news.gmane.io/gmane.comp.version-control.git
 note: .onion URLs require Tor: https://www.torproject.org/

code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git