Re: changelog format

[Alfred M. Szmidt]

   *** a/doc/standards.texi
   --- b/doc/standards.texi
   ***************
   *** 3516,3531 ****
     to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command
     @kbd{C-x v a} (@code{vc-update-change-log}) does the job.

   - There's no need to describe the full purpose of the changes or how
   - they work together.  However, sometimes it is useful to write one line
   - to describe the overall purpose of a change or a batch of changes.  If
   - you think that a change calls for explanation, you're probably right.
   - Please do explain it---but please put the full explanation in comments
   - in the code, where people will see it whenever they see the code.  For
   - example, ``New function'' is enough for the change log when you add a
   - function, because there should be a comment before the function
   - definition to explain what it does.

Why is this section removed?

     In the past, we recommended not mentioning changes in non-software
     files (manuals, help files, etc.) in change logs.  However, we've been
     advised that it is a good idea to include them, for the sake of
   --- 3516,3521 ----
   ***************
   *** 3536,3541 ****
   --- 3526,3558 ----
     asterisk, the name of the changed file, and then in parentheses the name
     of the changed functions, variables or whatever, followed by a colon.
     Then describe the changes you made to that function or variable.
   + Each group of related entries should have a @dfn{title}, a one line
   + description or summary of the change, and optionally a short
   + paragraph to:

I find the wording confusing here, and don't really understand what is
optional, or mandatory.  Making the description line (title is
confusing) mandatory is bad.  Many changes don't require it.

   + @table @asis
   + @item describe motivation
   + A change conceptually has three parts: before, why and after.
   + ``Before'' and ``after'' are captured in the version control system,
   + but where to capture ``why'' depends on what changed.  When source
   + code changes in a small number of files, the best place for ``why'' is
   + in the comments.  For other circumstances---many files or changes to
   + files that do not support a comment syntax---the change log is the
   + best place.

I would skip the `many files, no comment syntax' part, or atleast the
`no comment' bit since such files are not very common, and it is
trivial to preprocess them through grep or sed allowing for comments.

   + @item link to external resources
   + This includes bug report or mailing list URLs.

I would suggest: "This includes bug report IDs, URLs to related
mailing list threads, etc.".  Citing the URL to a bug report is
generally bad, since it might change.  Personally I am not fond of
citing the mailing list thread, such information should be distilled
and put into comments, or documentation.

   + @item link to another entry
   + This is useful when a change is a fix or continuation
   + of a previous change.

What does `another entry' mean in this context?  Another ChangeLog
entry?

   + @item give credit
   + It is courteous to acknowledge the help of others.  Although such
   + information may be available indirectly through a URL, including it
   + in the change log fosters community spirit and makes it more
   + self-contained.
   + @end table

I don't think ChangeLog shouldn't be used to give credit, that is what
AUTHORS and then THANKS files are used for; see the GNU Maintainer
Guide for details.  Or atleast, it shouldn't be encouraged as the
place for saying thank you.

     @node Style of Change Logs
     @subsection Style of Change Logs
   ***************
   *** 3544,3550 ****
     Here are some simple examples of change log entries, starting with the
     header line that says who made the change and when it was installed,
     followed by descriptions of specific changes.  (These examples are
   ! drawn from Emacs and GCC.)

     @example
     1998-08-17  Richard Stallman  <rms@@gnu.org>
   --- 3561,3567 ----
     Here are some simple examples of change log entries, starting with the
     header line that says who made the change and when it was installed,
     followed by descriptions of specific changes.  (These examples are
   ! drawn from Emacs and GCC, from back when the title was optional.)

Making it the description line mandatory is definitly a bad idea.

     @example
     1998-08-17  Richard Stallman  <rms@@gnu.org>
   ***************
   *** 3609,3614 ****
   --- 3626,3664 ----

     As for the date, that should be the date you applied the change.

   + In the short paragraph, URLs should have angle braces and (non-patch)
   + credits may optionally exclude the contributor's email address.  (A
   + patch should be handled as described above.)  

")." over ".)" please :-)

   A link to another entry
   + should be expressed as a date and an optional title, if the date is
   + insufficient to uniquely identify the precedent.  We recommend this

What about "A reference to another entry should be expressed as a date
and optionally a title if the date is insuficient to uniquely identify
the reference."

   + over using a version control system commit identifier for two
   + reasons: if the project changes version control systems, then those
   + identifiers will dangle uselessly; and using a date (and maybe title)
   + makes the change log self-contained.
   + 
   + Whether or not to add extra blank lines around the short paragraph is
   + up to you.  If so, each group of changes should have its own heading.
   + (In Emacs, set @code{add-log-always-start-new-record} to @code{t}.)
   + 
   + Likewise, what constitutes the title is up to you.
   + We note here only that many projects use the form:
   + @var{topic}[, @address@hidden: @var{description}.

I'm really against making the description line mandatory, but if that
would be the case it must have a fixed format and not be ad-hoc.  Then
one can make Emacs insert such a line.

I would like to see more examples, examples are really good source to
put your mind at reset.

Nice job.