On Wed, Jan 13, 2010 at 04:38:22PM +0100, Julia Lawall wrote: > > When you write a changelog, keep your audience in mind: > > > > - Developers, distributors, advanced users want to learn what a new > > release brings. (OK, this audience stops reading after the initial > > headline of a "make XYZ table constant" commit. Which just means > > that all the rest of the changelog is fluff that can be omitted.) > > > > - Developers, maintainers etc. want to understand years later why the > > code is how it is. (For them, a commit like that is sufficiently > > described by the headline as well.) > > Not surprisingly, I don't agree about this one. I recall a series of > patches that said something like "used a script to change down/up to > mutexes". The script wasn't included, not all down/ups were changed to > mutexes, and in short there was no understandable trace of why the change > was made where it was. Perhaps that is a pathological example, but it is > not necessarily obvious in advance what needs precise documentation and > what does not. I agree with Julia, at least in some cases. Having the semantic patch present when it's 5 or 10 lines long and clearly explains the intended change is incredibly valuable for review. Sometimes, the script is the clearest way to indicate your intent -- I'd much rather see a changelog that says "s/FOO/BAR/g" than "Change FOO to BAR everywhere". For example, look at 5d66fe92. The semantic patch is blissfully, incredibly clear. It makes the sun shine down through the clouds, the birds sing, and the kzalloc align. It's 10 lines long and is quite intuitive and explanatory. In that case, I think it's clear that the spatch is worth the changelog space it takes up, even though the changelog is larger than the diff by quite a margin. On the other hand, the patch that started this thread is a counterexample, to me. The correctness of the constification is only tenuously attested, for me at least, by the semantic patch. The spatch is really long compared to the diff, and complicated to read. So, I think it's a balancing act. I've been very happy to see spatches in some of Julia's posts, and I've also found some of the more voluminous spatches in changelogs to be more noise than signal. -andy -- To unsubscribe from this list: send the line "unsubscribe linux-usb" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
