On 12/22/2011 06:19 PM, Thien-Thi Nguyen wrote: > () Stefano Lattarini <[email protected]> > () Wed, 21 Dec 2011 09:52:55 +0100 > > I have a few objections against making the format you propose the base of > the ChangeLog entry format to be suggested in the GCS. See my comments > inline, below. > > Thanks for looking it over. > Thanks to you for working on it ;-)
> bug-standards perhaps? (but I'm not any more sure that you are). > > Fine w/ me. CC changed. > Good. > > Most information about the change should be placed in the source > > code comments. SHORT-PARAGRAPH is for referencing bug reports, > > giving credit (i.e., "Reported by" and "Suggested by" blurbs), > > and pointers to the origin of regressions > > > So your proposed format doesn't explicitly allow for a high-level, "global" > explanation of what a change does, and perhaps even more importantly, why. > This is an unacceptable limitation IMO. > > After reading your explanation of this kind of text (in another part of > the thread), i have come to agree. SHORT-PARAGRAPH should include > "motivation for change". How about this? > > SHORT-PARAGRAPH is for describing the motivation for the change, > i.e., "why", including perhaps a summary of the pre-change state. > (Information about the post-change state should be placed in the > source code comments.) > I'd do "s/should be placed/are usually better placed/", to give some slack and accomodate the not-so-common-but-no-so-rare cases where adding comments about the post-change state to the ChangeLog entry is useful or worthwhile. Maybe, if you fee like it, you could add a mild warning against the mistake of placing too much comments in the ChangeLog entry and too few in the code (I succumbed to this error few times already, and I see why warning against it might be warranted). Your call. SHORT-PARAGRAPH should also reference bug > reports, give credit (i.e., "Reported by" and "Suggested by" > blurbs), and give pointers to the origin of regressions. > > > (using conventional format "Regression introduced YYYY-MM-DD [TITLE].") > > Some packages prefer to refer to the VCS revision as well (or exclusively). > This is a point were we can give individual packages some slacks IMHO. > WDYT? > > Agreed. I think ‘s/conventional/the suggested/’ is indicated, plus the > sentence: "(The intent of this format is to make it easy to search for > that particular ChangeLog entry as well as give an immediate sense of > how long the problem persisted.)" > +1 on this. But you might also want to point out explicitly that some projects also refer to VCS revision, and that it is accepted practice. > > "U" means "Use ‘func’". > > > This just seems confusing to me; while I don't strongly object to > individual > packages using this "trick" if they find it useful, I'd rather not see it > in > an examples in the GCS. > > Right, too ttn-specific. Drop it. > Thanks. > > In this particular example, you can also write: > > > > Here, all C files now #include "header.h". > > * foo.c (foo): Use ‘func’. > > * bar.c (bar, baz): Likewise. > > (qux): Update call to ‘bar’. > > * doc.texi (ref): Mention "header.h". > > > This is what I'd do. > > Then we can just drop the first part, or explain better the idea > behind it. > > ENTRY-CONVENTIONS describe entry-specific abbreviations or > implicitly shared descriptions. The idea is to factor out common > bits of text, for readability, while preserving the full name of > functions or other code elements. > This might be overly-specific... I'm not opposed to it (rather I'm somewhat indifferent), but I so think it would be better to propose it in a separate, follow-up patch. Your choice though, I won't object anyway. > > ***** entries titled with suffix "; nfc." > > No strong opinion about this; but it seems to me that it might preferable > to > explicitly leave it to individual projects to decide whether to use this > particular convention, or to always prefer something like: > > [maint] Add top-level file HACKING > > * HACKING: New file. > > instead. > > Probably best to drop this entirely. > Yes. Thanks. > > ***** conventions for TITLE > > ******* tag > > To help identify the area of the change, include one or more > > tags in square braces at the beginning of the TITLE. > > > Many other gnu packages prefer the format: > > topic: brief description > > to the one you are proposing, that if I'm not mistaken is: > > [topic] brief description > > Should we try a poll of existing packages to decide which format to > choose, or is this another area where to leave the packages some > slack? > > Hmm... > > > For > > example, ‘maint’ for maintenance, ‘int’ for internal, ‘api’, > > ‘guile’, etc. Because space in the TITLE is limited, tags > > should be short and (if more than one) separated by a space. > > For example: > > > > [guile int] Avoid deprecated libguile elements. > > This example shows why i prefer tags: you can use them multiply. > Or you could do: guile, int: Avoid deprecated libguile elements. ;-) > Having said that, i realize that people see things differently. > How about adding: > > Alternatively, if there is no need for multiple tags, you can use > the more succinct form: > > TOPIC: BRIEF-DESCRIPTION > > This way, there is slack, but not too much slack. > Hmm... I'd rather not have two ways of formatting the so-fundamental title line. I think we should try to settle on one if possible. Regards, Stefano
