Re: changelog format

[Thien-Thi Nguyen]

() address@hidden (Alfred M. Szmidt)
() Tue, 17 Jan 2012 14:44:05 -0500

      - There's no need to describe the full purpose of the
      [...]
      - function definition to explain what it does.

   Why is this section removed?

Because it mixes concepts and style (the "however, sometimes
... batch of changes"), and because the advice on writing comments
is no longer fully applicable (to non-software files, mentioned
first in the following paragraph).  Such advice is now an
"implementation detail", dependent on the kind of change to be
logged.

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

OK.

   Making the description line (title is confusing)

To me, "title" suggests succinctness and overall applicability,
and is itself succinct.  What would you suggest instead?

   mandatory is bad.  Many changes don't require it.

I'm ambivalent, but only because i still use RCS, for which it
does seem overkill to require TITLE (though, i have developed a
habit of including one, anyway).  I expect those who use a VCS w/
proper change-set (multiple files) model would not find such a
requirement onerous.  Rather, it's common contemporary practice.

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

This paragraph covers non-text formats as well, such as image
files (e.g., converting a set of PNGs to remove alpha channel).
Such changes might indeed be uncommon, but they do happen.  I've
changed an initial blurb to mention this (saying "media files"
instead of "help files").

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

OK, good idea.  The text now reminds the reader that link
permanence is an important criteria.

   Personally I am not fond of citing the mailing list thread,
   such information should be distilled and put into comments, or
   documentation.

Personally, i'm not fond of long URLs.

      + @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?

Yes.  Well, maybe.  After re-reading, i see that "entry"
traditionally refers to a single change in a file, that is the
part that starts with asterisk.

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

   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.

I agree, somewhat.  I included this item mostly as a nod to
existing practice (and font-lock support in Emacs).  Perhaps we
can de-emphasize it here, and/or link to the maintainer guide.
... Hmm, i see maintain.texi does not mention THANKS.

        followed by descriptions of specific changes.  (These examples are
      ! drawn from Emacs and GCC.)

      --- 3561,3567 ----

        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.

Why?

      + (A patch should be handled as described above.)

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

I never realized there was this option.  I've side-stepped the issue by
removing that sentence.

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

Yes, that's better.

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

It's no big deal for Emacs to support project-specific formatting,
so i'm inclined to leave it as-is.  Another point of contention we
sidestep through loose specification is how to end the title -- some
projects prescribe punctuation, some proscribe it, some don't care.

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

Maybe you mean "rest"?  Anyway, i agree.

   Nice job.

Thanks for the review.  Please find attached the latest patch.