Re: The perfect patch - Posting a patch series (was Re: [PATCH 06/12] pci : Use mutex instead of semaphore in driver core)

["Dave Young" <hidave.darkstar@gmail.com>]

On Jan 2, 2008 7:14 PM, Stefan Richter <stefanr@s5r6.in-berlin.de> wrote:
> Dave Young wrote:
> > On Dec 29, 2007 7:42 PM, Stefan Richter <stefanr@s5r6.in-berlin.de> wrote:
> >> However, Dave's postings lack a References: header which refer to his
> >> 00/12 posting.
> [To let mail readers show it as a thread.]
> >> (Also, a bonus in the 00/12 posting would be a listing of all patch
> >> titles in the series and the total diffstat of the series,
> [similar to the "git pull" requests from maintainers]
> >> but nearly nobody does this.)
> ...
> > andrew recommends not to use 00/xx introduction email in series
> > in his "The perfect patch":
> > http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt
>
> "Please don't post [PATCH 0/n] messages" is a simplified short-hand for
> "Please don't move information which we want to include into the SCM
> changelog into a separate [PATCH 0/n] message".
>
> There is nothing wrong with a 0/n posting per se.  But whenever you
> write a 0/n posting, ask yourself:
>   - Isn't the information I provide here necessary to keep around by
>     somebody who takes my patch series into his quilt series or into his
>     source repository?
>   - Couldn't the information here be useful at a later point in time
>     when people look into the mainline Linux history?
> If "yes" or "maybe yes", then add this information to the changelogs in
> the patches.  You can then leave the 0/n posting as is, or make it
> briefer, or omit it entirely.
>
> It is never necessary to post a 0/n message, because _everything_ which
> could be said in this message can also be said in the i/n messages.
> (Things which are not meant for the SCM changelog can be written after a
> "---" delimiter line or other patch delimiters.)  However, it is
> sometimes convenient to repeat or summarize some of the information from
> the i/n messages in a 0/n message.  Think about convenience of the
> _recipients_ though, not about the sender's convenience.
>
> Generally, the 0/n message fulfills purposes very similar to "git pull"
> messages:  They give a brief overview of what is coming up in the series
> and how to handle it, and it adds redundant information about the
> contents of the series (titles, authors, overall diffstat, whether it
> supersedes an earlier series) as a verification for the recipient
> whether he really got what the sender intended to get to him.  This is
> to help detect mix-ups at the sender's or receiver's side.
>
> PS:
> Writing a changelog is almost never trivial.  Even if it seems trivial
> to the patch author, the change may not be trivial from other
> developers' and maintainers' perspective, or from the author's
> perspective when he looks at his patch a few months later.  This also
> means that there may very well be information in the 0/n message which
> should also appear in the i/n messages, even if this information seems
> obvious to the author.

Thanks for the explanation, I strongly agree with you.
I think that 0/n message should be a summary of the series. At the
same time the i/n changelog should not be stripped, any info of
changes should be added to the relavant patches.

Regards
dave