Cover Letter of Patchsets

Cover Letter of Patchsets

[Leo Liang]

Hi Tom,

I am Leo, just recently joined the community.
and been picking up the guide line of uboot's development.

I am a bit curious about the policy on the cover letter of patchsets.
Is cover letter mandatory ?

IMHO, making it mandatory, especially on patchsets that consist of more than 1 patch, is more than useful and of great advantages.

1. Making patches clearer for peer and maintainer review
   
   The reviewer and maintainer could immediately understand,
   or at least get the idea of, the whole patchset
   through only reading this ONE cover letter
   without having to dive into each of the patch.

   And thus quickly determine if the patchset solves the problem
   or if the patchset is well organized.

2. Helping the author better organize the patchset
   
   Writing the cover letter would require the author 
   to scrutinize the patchset structure again,
   in order to elaborate his/her craft.

   So when composing the letter, the relevance of each patch
   would be thoroghly looked over and the patchset might be
   refined into small but more closely-related patchsets.

   And it would be easier for the maintainer to pull small gradual changes 
   than a huge patchset with lots of changes at once.
   

In all, I think it would be nice to write cover letter to introduce the work.

If I miss anything or misunderstand anything please let me know, thanks in advance.

Best regards,
Leo

Cover Letter of Patchsets

[Wolfgang Denk]

Dear Leo,

In message <20200706023510.GB2522@andestech.com> you wrote:
>
> I am Leo, just recently joined the community.
> and been picking up the guide line of uboot's development.
>
> I am a bit curious about the policy on the cover letter of patchsets.
> Is cover letter mandatory ?

No, it is not really mandatoryh, but strongl recommended for patch
series.

> IMHO, making it mandatory, especially on patchsets that consist of
> more than 1 patch, is more than useful and of great advantages.

For single patches a cover letter usually makes little sense.

> 1. Making patches clearer for peer and maintainer review
...
> 2. Helping the author better organize the patchset
...
> In all, I think it would be nice to write cover letter to introduce the work.

All your arguments make a lot of sense, indeed.

> If I miss anything or misunderstand anything please let me know, thanks in advance.

Please keep in mind that an inherent property of the cover letter is
that it is NOT part of the patches itself, i. e. it helps only
during the review process, but not any time later when someone tries
to understand the code from reading the git commit logs.


So the essential information to understand the purpose and the
implementation (and ideally also how it has been tested / can be
tested) should always be part of the commit messages itself.

THe cover letter can summarize such information and provide the
overview information for a patch series.  Also it should commet on
the changes between versions of the patch series, if these are
needed (especially when major rework is done between submissions).

But it is only supplementary information which gets lost when the
patches are pulled into the git repository.

Best regards,

Wolfgang Denk

-- 
DENX Software Engineering GmbH,      Managing Director: Wolfgang Denk
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
"Where shall I begin, please your Majesty?" he asked. "Begin  at  the
beginning,"  the  King said, gravely, "and go on till you come to the
end: then stop."    - Alice's Adventures in Wonderland, Lewis Carroll

Cover Letter of Patchsets

[Leo Liang]

Dear Wolfgang,

On Mon, Jul 06, 2020 at 08:03:46PM +0800, Wolfgang Denk wrote:
> Dear Leo,
> 
> In message <20200706023510.GB2522@andestech.com> you wrote:
> >
> > I am Leo, just recently joined the community.
> > and been picking up the guide line of uboot's development.
> >
> > I am a bit curious about the policy on the cover letter of patchsets.
> > Is cover letter mandatory ?
> 
> No, it is not really mandatoryh, but strongl recommended for patch
> series.
> 
> > IMHO, making it mandatory, especially on patchsets that consist of
> > more than 1 patch, is more than useful and of great advantages.
> 
> For single patches a cover letter usually makes little sense.
> 
> > 1. Making patches clearer for peer and maintainer review
> ...
> > 2. Helping the author better organize the patchset
> ...
> > In all, I think it would be nice to write cover letter to introduce the work.
> 
> All your arguments make a lot of sense, indeed.
> 
> > If I miss anything or misunderstand anything please let me know, thanks in advance.
> 
> Please keep in mind that an inherent property of the cover letter is
> that it is NOT part of the patches itself, i. e. it helps only
> during the review process, but not any time later when someone tries
> to understand the code from reading the git commit logs.
> 
> 
> So the essential information to understand the purpose and the
> implementation (and ideally also how it has been tested / can be
> tested) should always be part of the commit messages itself.
> 
> THe cover letter can summarize such information and provide the
> overview information for a patch series.  Also it should commet on
> the changes between versions of the patch series, if these are
> needed (especially when major rework is done between submissions).
> 
> But it is only supplementary information which gets lost when the
> patches are pulled into the git repository.
> 

Understood!
Thank you very much for the clarification.

Best regards,
Leo