1This is an essay by Jim Blandy <jimb@redhat.com> on maintaining
2ChangeLog entries.  
3
4Although Subversion generates its ChangeLogs from svn log data,
5instead of keeping independent ChangeLog files, most of the advice
6below is as applicable to cvs log messages as to ChangeLog entries.
7
8
9Maintaining the ChangeLog
10=========================
11
12A project's ChangeLog provides a history of development.  Comments in
13the code should explain the code's present state, but ChangeLog
14entries should explain how and when it got that way.  The ChangeLog
15must 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
24In the case of CVS, these refer to when the change was committed,
25because that is the context in which other developers will see the
26change.
27
28Every change to the sources should have a ChangeLog entry.  The value
29of the ChangeLog becomes much less if developers cannot rely on its
30completeness.  Even if you've only changed comments, write an entry
31that says, "Doc fix."  The only changes you needn't log are small
32changes that have no effect on the source, like formatting tweaks.
33
34In order to keep the ChangeLog a manageable size, at the beginning of
35each year, the ChangeLog should be renamed to "ChangeLog-YYYY", and a
36fresh ChangeLog file started.
37
38
39How to write ChangeLog entries
40------------------------------
41
42ChangeLog entries should be full sentences, not sentence fragments.
43Fragments are more often ambiguous, and it takes only a few more
44seconds to write out what you mean.  Fragments like `New file' or `New
45function' are acceptable, because they are standard idioms, and all
46further details should appear in the source code.
47
48The log entry should mention every file changed.  It should also
49mention by name every function, variable, macro, makefile target,
50grammar rule, etc. you changed.  However, there are common-sense
51exceptions:
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
61In general, there is a tension between making entries easy to find by
62searching for identifiers, and wasting time or producing unreadable
63entries by being exhaustive.  Use your best judgement --- and be
64considerate of your fellow developers.
65
66Group ChangeLog entries into "paragraphs", separated by blank lines.
67Each paragraph should be a set of changes that accomplish a single
68goal.  Independent changes should be in separate paragraphs.  For
69example:
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
82Even though this entry describes two changes to `configure.host',
83they're in separate paragraphs, because they're unrelated changes.
84The second change to `configure.host' is grouped with another change
85to `configure.tgt', because they both serve the same purpose.
86
87Also note that the author has kindly recorded his overall motivation
88for the paragraph, so we don't have to glean it from the individual
89changes.
90
91The header line for the ChangeLog entry should have the format shown
92above.  If you are using an old version of Emacs (before 20.1) that
93generates entries with more verbose dates, consider using
94`etc/add-log.el', from the GDB source tree.  If you are using vi,
95consider using the macro in `etc/add-log.vi'.  Both of these generate
96entries in the newer, terser format.
97
98One should never need the ChangeLog to understand the current code.
99If you find yourself writing a significant explanation in the
100ChangeLog, you should consider carefully whether your text doesn't
101actually belong in a comment, alongside the code it explains.  Here's
102an 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
109And 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
125This 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
128Avoid the temptation to abbreviate filenames or function names, as in
129this 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
136This makes it difficult for others to search the ChangeLog for changes
137to the file or function they are interested in.  For example, if you
138searched for `set_gdbarch_long_bit', you would not find the above
139entry, because the writer used CSH-style globbing to abbreviate the
140list of functions.  If you gave up, and made a second pass looking for
141gdbarch.c, you wouldn't find that either.  Consider your poor readers,
142and write out the names.
143
144
145ChangeLogs and the CVS log
146--------------------------
147
148CVS maintains its own logs, which you can access using the `cvs log'
149command.  This duplicates the information present in the ChangeLog,
150but binds each entry to a specific revision, which can be helpful at
151times.
152
153However, 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
164In some circumstances, though, the CVS log is more useful than the
165ChangeLog, so we maintain both.  When you commit a change, you should
166provide appropriate text in both the ChangeLog and the CVS log.
167
168It is not necessary to provide CVS log entries for ChangeLog changes,
169since it would simply duplicate the contents of the file itself.  
170
171
172Writing ChangeLog entries for merges
173------------------------------------
174
175Revision management software like CVS can introduce some confusion
176when writing ChangeLog entries.  For example, one might write a change
177on a branch, and then merge it into the trunk months later.  In that
178case, what position and date should the developer use for the
179ChangeLog entry --- that of the original change, or the date of the
180merge?
181
182The principles described at the top need to hold for both the original
183change 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
217This approach preserves the structure of the ChangeLog (entries appear
218in order, and dates reflect when they appeared), but also provides
219full information about changes' origins.
220
221