Re: [gnu-prog-discuss] An experimental GNU Assembly

[Thien-Thi Nguyen]

() 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.

   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.)  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.)"

   >         "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.

   >       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.

   > ***** 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.

   > ***** 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.
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.