[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [gnu-prog-discuss] An experimental GNU Assembly
Re: [gnu-prog-discuss] An experimental GNU Assembly
Thu, 22 Dec 2011 18:35:09 +0100
Mozilla/5.0 (X11; U; Linux i686; en-US; rv:126.96.36.199) Gecko/20111114 Icedove/3.1.16
On 12/22/2011 06:19 PM, Thien-Thi Nguyen wrote:
> () Stefano Lattarini <address@hidden>
> () 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.
> > 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.
> 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
> packages using this "trick" if they find it useful, I'd rather not see it
> an examples in the GCS.
> Right, too ttn-specific. Drop it.
> > 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
> 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.
> Probably best to drop this entirely.
> > ***** 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
> > 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.