Hi Thien-Thi. On 05/24/2012 11:15 AM, Thien-Thi Nguyen wrote: > () [email protected] (Karl Berry) > () Wed, 23 May 2012 22:29:31 GMT > > The more and smaller pieces there are, with the most concise (and > convincing :) possible rationale, the more likely he will accept a > change. (Of course, changes that are truly interdependent and don't > make sense separately should be presented together as one change. > I'm not talking about technical hunks in a diff.) > > Thanks for the reminder (and to everyone for their patience). Perhaps > rather than post diffs and discuss them, i should have started with the > discussion. I'll try that now. I think logically, the changes i'd like > to see can be broken down in small pieces: > > 1 -- Expand "other files for which changes should be logged" to say > explicitly "media files" instead of "help files". > > Rationale: (a) increasing relevance of media files for certain > program classes; (b) better (more orthogonal) "coverage", since > "help files" and "manuals" overlap conceptually; (c) see point 3. > > 2 -- Clarify "change log entry", making a distinction between a "change > set" (introducing this term) and an "individual change". A single > change log entry corresponds to a change set, which comprises one > or more individual changes. Leave granularity of "individual > change" (file, func, form) open to interpretation. > > Rationale: Although people can infer "batch of changes" to mean > "change set", the latter is current and it's better to be explicit. > Separating "change log entry" from "individual change" and instead > associating it with "change set" makes it easier to refer to later > (see point 5, below). > +0
I have no strong feelings on these, so I won't comment, and I'll agree with the decisions the other people here will make. > 3 -- (dependent on points 1 and 2) Endorse the changelog as the *best* > place for rationale/why information for: > > - files that don't support comment syntax (e.g., media files); > > - a large change set, where something like: > > /* We need this for func 'foo', which used to be available > (conditionally) from "xyz.h" for system XYZ, but now > gnulib DTRT (unconditionally). */ > #include "header.h" > > in N files could benefit from factoring the N comments to a > single instance in the changelog. > > Rationale: We currently urge rationale/why information to be placed > in the comments, and that should not change. This change maintains > that spirit, giving guidance for cases when "comments in code" is > impossible or unwieldy. > IMHO, this misses the most important scenario where comments in a ChangeLog entries are justified (I'd say required): explaining the *why* of a *change*. See my lengthy explanations in: <http://lists.gnu.org/archive/html/bug-standards/2012-05/msg00000.html> <http://lists.gnu.org/archive/html/bug-standards/2012-05/msg00009.html> the main point that can be condensed from there being: The how and why the code works the way it works -- yes, that must definitely must go in code comments (albeit in most cases, placing also an "abridged" version in the commit message as well won't hurt). But the rationale of why a change is needed, and how it relates to previous changes or attempts -- that must go in the commit messages (albeit in some cases, reporting part of that history in code comments can be of great help). > 4 -- Suggest TITLE (aka DESCRIPTION LINE) format; keep it optional. > > Rationale: This documents current practice. > And makes life easier for people syncing ChangeLog entries with VCS commit messages, since prominent version control systems (like git) handles the first line of a commit somewhat specially (expecting it to be a summary line). > Originally, i had > wanted TITLE to be mandatory, but now i'm convinced that some > projects don't need it. > +0.5 I'm still not convinced that lacking a summary line is ever a good idea, but I've agreed that recommending the summary line instead of mandating it is still a good compromise. So let's got for it. > 5 -- (in line with 3, dependent on 4) Encourage "moderate" reference > information, in the form of previous change log entries, bug id > URIs, etc, in a standardized format. Likewise w/ credits (e.g., > "Reported by"), taking care to emphasize THANKS and AUTHORS as > authoritative. Give some privacy guidelines while we're at it. > > Rationale: This documents current practice, including explicit > support by tools such as Emacs. Also, THANKS is currently not > mentioned in {maintain,standards}.texi. A little redundancy here > is a small price for increased community spirit. > +1 > Overall, the thrust is to edge ChangeLog files outward from strictly > "what changed" ever so slightly towards "what changed and why", in the > process making it easier to *follow* a chain of "what changed". I think > this is useful because jumping inside another's mind is not easy at all! > This is doubly difficult when there are multiple jumps required. > > Anyway, now i'll submit the above pieces in new threads, starting w/ 0 > and waiting to conclude one before starting another -- Karl: is that the > best way? One important point previously discussed but omitted above is > addition of examples. Those will accompany the patches. > Thanks for all your work on this, Stefano
