Re: [PATCH 2/2] SubmittingPatches: describe cover letter

[Derrick Stolee <stolee@gmail.com>]

On 6/2/2026 5:08 AM, Junio C Hamano wrote:
> We talk about how a commit log message should look like, but do not
> give advice on writing the cover letter to sell a series to widest
> possible audience.

This is a good thing to boost in the documentation.

> +[[cover-letter]]
> +=== Cover Letter
> +
> +The purpose of your cover letter is to sell your changes, explain what
> +they are about, and get your target audience interested enough to read
> +the patches.
> +
> +. Make sure your target audience can understand what the patches are
> +  about and why they are needed without prior context.

The thing that I like to say about the cover letter is that this is
your opportunity to communicate why the value of your change is worth
the risk of regressions and the cost of maintenance. Perhaps:

. Every code change comes with risk of regression and maintenance cost.
  The cover letter should clearly communicate why the value of your
  proposed change is worth applying. You can also describe how the risk
  is reduced by the design choices you made while writing the patches.

Or something similar may be helpful? I may just be over explaining.

> +. For a second or subsequent iteration of the same topic, make sure
> +  people who missed the earlier discussion can still understand what
> +  the patches are about, so they can judge if the topic is worth their
> +  time to read and comment on.
> +
> +. To help those who are familiar with earlier iterations, give a
> +  summary of changes since the previous rounds.
I find these updates to be particularly helpful, even for GitGitGadget
PRs that include a range-diff automatically. It's good to double-check
the human description of the update against the computed diff.

Thanks,
-Stolee