.be/bugs/529c290e-b1cf-4800-be7e-68f1ecb9565c/comments/2bb7b4d0-6290-4771-9fff-4aa2e8086b1a/body

   1 Chris Ball <cjb@laptop.org> writes:
   2
   3 > Hi,
   4 >
   5 >    > That's not a changelog, that's a commit log of every source-level
   6 >    > commit made. Far too much detail for a changelog of
   7 >    > *user-visible* changes associated with a release.
   8 >
   9 > I think I agree with both of you. :) It seems like it's both true that
  10 > there's no point in keeping a GNU-style ChangeLog these days
  11
  12 I think I have a better understanding of why this apparent disagreement
  13 occurred, and it was due to my sloppy use of terms.
  14
  15 Looking into it further, it seems there is a certain expectation (set,
  16 in part, by the long-standing GNU coding conventions) that a “GNU-style
  17 ChangeLog” contains not only a particular *format*, but information at
  18 a particular level of *detail*.
  19
  20 That is, a GNU ChangeLog is intended for the style of work where one
  21 logs all the changes made to every file in the tree each working day,
  22 and then makes a new day's entry above that, and so on. This is, of
  23 course, entirely redundant with a VCS revision history, which makes all
  24 the commit messages available on request.
  25
  26 So to disambiguate, that's not what I meant. I'm more familiar with a
  27 less-frequently-updated and less-fine-detail change log; perhaps more
  28 akin to the GNU-style “NEWS” file.
  29
  30 > and that if we make a release we should write an announce mail that
  31 > directly mentions new user-visible changes as well as attaching the
  32 > commit log. That smaller list of highly user-visible changes could
  33 > live in NEWS, or in the announce mail, or both.
  34
  35 Yes, that's mostly what I meant.
  36
  37 I actually don't think the commit log needs to be part of the release at
  38 all. It's of interest only to those who want fine-level detail about
  39 changes to every file, and for that purpose I think read access to the
  40 VCS is much better. Packaging a static copy of the commit log as plain
  41 text seems pointless.
  42
  43 Rather, we should treat a user-changes level “NEWS” file (or whatever
  44 name we choose for it) as part of the documentation, and set the
  45 expectation among the team that it will be updated for each user-visible
  46 change being worked on, like any other documentation.
  47
  48 --
  49  \            “… Nature … is seen to do all things Herself and through |
  50   `\         herself of own accord, rid of all gods.” —Titus Lucretius |
  51 _o__)                                                 Carus, c. 40 BCE |
  52 Ben Finney
  53
  54
  55 _______________________________________________
  56 Be-devel mailing list
  57 Be-devel@bugseverywhere.org
  58 http://void.printf.net/cgi-bin/mailman/listinfo/be-devel