Re: The perfect patch - Posting a patch series (was Re: [PATCH 06/12] pci : Use mutex instead of semaphore in driver core)
From: Dave Young
Date: Thu Jan 03 2008 - 01:11:08 EST
On Jan 2, 2008 7:14 PM, Stefan Richter <stefanr@xxxxxxxxxxxxxxxxx> wrote:
> Dave Young wrote:
> > On Dec 29, 2007 7:42 PM, Stefan Richter <stefanr@xxxxxxxxxxxxxxxxx> 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.
> 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.
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/