doc/programmer/WritingChangeLogs.txt

   1 This is an essay by Jim Blandy <jimb@redhat.com> on maintaining
   2 ChangeLog entries.
   3
   4 Although Subversion generates its ChangeLogs from svn log data,
   5 instead of keeping independent ChangeLog files, most of the advice
   6 below is as applicable to cvs log messages as to ChangeLog entries.
   7
   8
   9 Maintaining the ChangeLog
  10 =========================
  11
  12 A project's ChangeLog provides a history of development.  Comments in
  13 the code should explain the code's present state, but ChangeLog
  14 entries should explain how and when it got that way.  The ChangeLog
  15 must show:
  16
  17 * the relative order in which changes entered the code, so you can
  18   see the context in which a change was made, and
  19
  20 * the date at which the change entered the code, so you can relate the
  21   change to outside events, like branch cuts, code freezes, and
  22   releases.
  23
  24 In the case of CVS, these refer to when the change was committed,
  25 because that is the context in which other developers will see the
  26 change.
  27
  28 Every change to the sources should have a ChangeLog entry.  The value
  29 of the ChangeLog becomes much less if developers cannot rely on its
  30 completeness.  Even if you've only changed comments, write an entry
  31 that says, "Doc fix."  The only changes you needn't log are small
  32 changes that have no effect on the source, like formatting tweaks.
  33
  34 In order to keep the ChangeLog a manageable size, at the beginning of
  35 each year, the ChangeLog should be renamed to "ChangeLog-YYYY", and a
  36 fresh ChangeLog file started.
  37
  38
  39 How to write ChangeLog entries
  40 ------------------------------
  41
  42 ChangeLog entries should be full sentences, not sentence fragments.
  43 Fragments are more often ambiguous, and it takes only a few more
  44 seconds to write out what you mean.  Fragments like `New file' or `New
  45 function' are acceptable, because they are standard idioms, and all
  46 further details should appear in the source code.
  47
  48 The log entry should mention every file changed.  It should also
  49 mention by name every function, variable, macro, makefile target,
  50 grammar rule, etc. you changed.  However, there are common-sense
  51 exceptions:
  52
  53 * If you have made a change which requires trivial changes throughout
  54   the rest of the program (e.g., renaming a variable), you needn't
  55   name all the functions affected.
  56
  57 * If you have rewritten a file completely, the reader understands that
  58   everything in it has changed, so your log entry may simply give the
  59   file name, and say "Rewritten".
  60
  61 In general, there is a tension between making entries easy to find by
  62 searching for identifiers, and wasting time or producing unreadable
  63 entries by being exhaustive.  Use your best judgement --- and be
  64 considerate of your fellow developers.
  65
  66 Group ChangeLog entries into "paragraphs", separated by blank lines.
  67 Each paragraph should be a set of changes that accomplish a single
  68 goal.  Independent changes should be in separate paragraphs.  For
  69 example:
  70
  71     1999-03-24  Stan Shebs  <shebs@andros.cygnus.com>
  72
  73             * configure.host (mips-dec-mach3*): Use mipsm3, not mach3.
  74
  75             Attempt to sort out SCO-related configs.
  76             * configure.host (i[3456]86-*-sysv4.2*): Use this instead of
  77             i[3456]86-*-sysv4.2MP and i[3456]86-*-sysv4.2uw2*.
  78             (i[3456]86-*-sysv5*): Recognize this.
  79             * configure.tgt (i[3456]86-*-sco3.2v5*, i[3456]86-*-sco3.2v4*):
  80             Recognize these.
  81
  82 Even though this entry describes two changes to `configure.host',
  83 they're in separate paragraphs, because they're unrelated changes.
  84 The second change to `configure.host' is grouped with another change
  85 to `configure.tgt', because they both serve the same purpose.
  86
  87 Also note that the author has kindly recorded his overall motivation
  88 for the paragraph, so we don't have to glean it from the individual
  89 changes.
  90
  91 The header line for the ChangeLog entry should have the format shown
  92 above.  If you are using an old version of Emacs (before 20.1) that
  93 generates entries with more verbose dates, consider using
  94 `etc/add-log.el', from the GDB source tree.  If you are using vi,
  95 consider using the macro in `etc/add-log.vi'.  Both of these generate
  96 entries in the newer, terser format.
  97
  98 One should never need the ChangeLog to understand the current code.
  99 If you find yourself writing a significant explanation in the
 100 ChangeLog, you should consider carefully whether your text doesn't
 101 actually belong in a comment, alongside the code it explains.  Here's
 102 an example of doing it right:
 103
 104   1999-02-23  Tom Tromey  <tromey@cygnus.com>
 105
 106           * cplus-dem.c (consume_count): If `count' is unreasonable,
 107           return 0 and don't advance input pointer.
 108
 109 And then, in `consume_count' in `cplus-dem.c':
 110
 111    while (isdigit ((unsigned char)**type))
 112      {
 113        count *= 10;
 114        count += **type - '0';
 115        /* A sanity check.  Otherwise a symbol like
 116          `_Utf390_1__1_9223372036854775807__9223372036854775'
 117          can cause this function to return a negative value.
 118          In this case we just consume until the end of the string.  */
 119       if (count > strlen (*type))
 120         {
 121           *type = save;
 122           return 0;
 123         }
 124
 125 This is why a new function, for example, needs only a log entry saying
 126 "New Function" --- all the details should be in the source.
 127
 128 Avoid the temptation to abbreviate filenames or function names, as in
 129 this example (mostly real, but slightly exaggerated):
 130
 131         * gdbarch.[ch] (gdbarch_tdep, gdbarch_bfd_arch_info,
 132         gdbarch_byte_order, {set,}gdbarch_long_bit,
 133         {set,}gdbarch_long_long_bit, {set,}gdbarch_ptr_bit): Corresponding
 134         functions.
 135
 136 This makes it difficult for others to search the ChangeLog for changes
 137 to the file or function they are interested in.  For example, if you
 138 searched for `set_gdbarch_long_bit', you would not find the above
 139 entry, because the writer used CSH-style globbing to abbreviate the
 140 list of functions.  If you gave up, and made a second pass looking for
 141 gdbarch.c, you wouldn't find that either.  Consider your poor readers,
 142 and write out the names.
 143
 144
 145 ChangeLogs and the CVS log
 146 --------------------------
 147
 148 CVS maintains its own logs, which you can access using the `cvs log'
 149 command.  This duplicates the information present in the ChangeLog,
 150 but binds each entry to a specific revision, which can be helpful at
 151 times.
 152
 153 However, the CVS log is no substitute for the ChangeLog files.
 154
 155 * CVS provides no easy way to see the changes made to a set of files
 156   in chronological order.  They're sorted first by filename, not by date.
 157
 158 * Unless you put full ChangeLog paragraphs in your CVS log entries, it's
 159   difficult to pull together changes that cross several files.
 160
 161 * CVS doesn't segregate log entries for branches from those for the
 162   trunk in any useful way.
 163
 164 In some circumstances, though, the CVS log is more useful than the
 165 ChangeLog, so we maintain both.  When you commit a change, you should
 166 provide appropriate text in both the ChangeLog and the CVS log.
 167
 168 It is not necessary to provide CVS log entries for ChangeLog changes,
 169 since it would simply duplicate the contents of the file itself.
 170
 171
 172 Writing ChangeLog entries for merges
 173 ------------------------------------
 174
 175 Revision management software like CVS can introduce some confusion
 176 when writing ChangeLog entries.  For example, one might write a change
 177 on a branch, and then merge it into the trunk months later.  In that
 178 case, what position and date should the developer use for the
 179 ChangeLog entry --- that of the original change, or the date of the
 180 merge?
 181
 182 The principles described at the top need to hold for both the original
 183 change and the merged change.  That is:
 184
 185 * On the branch (or trunk) where the change is first committed, the
 186   ChangeLog entry should be written as normal, inserted at the top of
 187   the ChangeLog and reflecting the date the change was committed to
 188   the branch (or trunk).
 189
 190 * When the change is then merged (to the trunk, or to another branch),
 191   the ChangeLog entry should have the following form:
 192
 193   1999-03-26  Jim Blandy  <jimb@zwingli.cygnus.com>
 194
 195            Merged change from foobar_20010401_branch:
 196
 197            1999-03-16  Keith Seitz  <keiths@cygnus.com>
 198            [...]
 199
 200   In this case, "Jim Blandy" is doing the merge on March 26; "Keith
 201   Seitz" is the original author of the change, who committed it to
 202   `foobar_20010401_branch' on March 16.
 203
 204   As shown here, the entry for the merge should be like any other
 205   change --- inserted at the top of the ChangeLog, and stamped with
 206   the date the merge was committed.  It should indicate the origin of
 207   the change, and provide the full text of the original entry,
 208   indented to avoid being confused with a true log entry.  Remember
 209   that people looking for the merge will search for the original
 210   changelog text, so it's important to preserve it unchanged.
 211
 212   For the merge entry, we use the merge date, and not the original
 213   date, because this is when the change appears on the trunk or branch
 214   this ChangeLog documents.  Its impact on these sources is
 215   independent of when or where it originated.
 216
 217 This approach preserves the structure of the ChangeLog (entries appear
 218 in order, and dates reflect when they appeared), but also provides
 219 full information about changes' origins.
 220