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, This "used a script to change down/up to mutexes" surely was meant to convey that the submitter performed a mass change on code that he is not particularly familiar with or frequently works with himself, i.e. it was a mostly mechanical change in contrast to how proposed changes are usually developed. Semaphore to mutex conversions are/have been not as trivial as for example a marking of an ID table as const. Hence those hints that this was a mostly mechanical conversion (certainly with some checking afterwards) usefully put the submission into perspective for reviewers. This information may also be useful after commit, hence it is good for the SCM's changelog. The find-and-replace macro itself and the processor which ran that macro during the development of such a sem2mutex change is entirely uninteresting. > not all down/ups were changed to mutexes, If that was unexplained, the it was probably an unintended result of the mechanical conversion by someone who does not have a deeper personal investment in the affected code, or simply missed something for whatever reason. If it was by mistake, inclusion of the find-and-replace script into the patch posting *after the --- delimiter* might have increased the chance that a patch reviewer becomes aware of a possible error source (inadequate match patterns...). So that could be useful during review before commit, but not so much if the change is revisited some time after commit. > and in short there was no understandable trace of why the change > was made where it was. Then that changelog was bad since it missed to document the "Why", which is one of the most important parts of a changelog. > Perhaps that is a pathological example, but it is > not necessarily obvious in advance what needs precise documentation and > what does not. Granted, it is subjective. The perfect changelog which is ideal for every possible audience does not exist. -- Stefan Richter -=====-==-=- ---= -==-= http://arcgraph.de/sr/ -- 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
