1
This is an essay by Jim Blandy <jimb@redhat.com> on maintaining
4
Although Subversion generates its ChangeLogs from cvs 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.
9
Maintaining the ChangeLog
10
=========================
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
17
* the relative order in which changes entered the code, so you can
18
see the context in which a change was made, and
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
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
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.
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.
39
How to write ChangeLog entries
40
------------------------------
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.
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
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.
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".
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.
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
71
1999-03-24 Stan Shebs <shebs@andros.cygnus.com>
73
* configure.host (mips-dec-mach3*): Use mipsm3, not mach3.
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*):
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.
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
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.
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:
104
1999-02-23 Tom Tromey <tromey@cygnus.com>
106
* cplus-dem.c (consume_count): If `count' is unreasonable,
107
return 0 and don't advance input pointer.
109
And then, in `consume_count' in `cplus-dem.c':
111
while (isdigit ((unsigned char)**type))
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))
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.
128
Avoid the temptation to abbreviate filenames or function names, as in
129
this example (mostly real, but slightly exaggerated):
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
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.
145
ChangeLogs and the CVS log
146
--------------------------
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
153
However, the CVS log is no substitute for the ChangeLog files.
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.
158
* Unless you put full ChangeLog paragraphs in your CVS log entries, it's
159
difficult to pull together changes that cross several files.
161
* CVS doesn't segregate log entries for branches from those for the
162
trunk in any useful way.
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.
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.
172
Writing ChangeLog entries for merges
173
------------------------------------
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
182
The principles described at the top need to hold for both the original
183
change and the merged change. That is:
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).
190
* When the change is then merged (to the trunk, or to another branch),
191
the ChangeLog entry should have the following form:
193
1999-03-26 Jim Blandy <jimb@zwingli.cygnus.com>
195
Merged change from foobar_20010401_branch:
197
1999-03-16 Keith Seitz <keiths@cygnus.com>
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.
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.
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.
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.
added
removed
doc/programmer/WritingChangeLogs.txt
