You are on page 1of 4

This is an essay by Jim Blandy <jimb@redhat.com> on maintaining ChangeLog entries.

Although Subversion generates its ChangeLogs from svn log data, instead of keeping independent ChangeLog files, most of the advice below is as applicable to cvs log messages as to ChangeLog entries. Maintaining the ChangeLog ========================= A project's ChangeLog provides a history of development. Comments in the code should explain the code's present state, but ChangeLog entries should explain how and when it got that way. The ChangeLog must show: * the relative order in which changes entered the code, so you can see the context in which a change was made, and * the date at which the change entered the code, so you can relate the change to outside events, like branch cuts, code freezes, and releases. In the case of CVS, these refer to when the change was committed, because that is the context in which other developers will see the change. Every change to the sources should have a ChangeLog entry. The value of the ChangeLog becomes much less if developers cannot rely on its completeness. Even if you've only changed comments, write an entry that says, "Doc fix." The only changes you needn't log are small changes that have no effect on the source, like formatting tweaks. In order to keep the ChangeLog a manageable size, at the beginning of each year, the ChangeLog should be renamed to "ChangeLog-YYYY", and a fresh ChangeLog file started. How to write ChangeLog entries -----------------------------ChangeLog entries should be full sentences, not sentence fragments. Fragments are more often ambiguous, and it takes only a few more seconds to write out what you mean. Fragments like `New file' or `New function' are acceptable, because they are standard idioms, and all further details should appear in the source code. The log entry should mention every file changed. It should also mention by name every function, variable, macro, makefile target, grammar rule, etc. you changed. However, there are common-sense exceptions: * If you have made a change which requires trivial changes throughout the rest of the program (e.g., renaming a variable), you needn't name all the functions affected. * If you have rewritten a file completely, the reader understands that everything in it has changed, so your log entry may simply give the file name, and say "Rewritten".

2v4*): Recognize these.tgt (i[3456]86-*-sco3.c (consume_count): If `count' is unreasonable. you should consider carefully whether your text doesn't actually belong in a comment.el'.'0'.c': while (isdigit ((unsigned char)**type)) { count *= 10. /* A sanity check. For example: 1999-03-24 Stan Shebs <shebs@andros. If you are using an old version of Emacs (before 20. and wasting time or producing unreadable entries by being exhaustive. consider using `etc/add-log.In general.host'.host' is grouped with another change to `configure.com> * cplus-dem. Otherwise a symbol like `_Utf390_1__1_9223372036854775807__9223372036854775' can cause this function to return a negative value. Independent changes should be in separate paragraphs. Also note that the author has kindly recorded his overall motivation for the paragraph. Both of these generate entries in the newer. because they both serve the same purpose.host (mips-dec-mach3*): Use mipsm3. One should never need the ChangeLog to understand the current code. The header line for the ChangeLog entry should have the format shown above. consider using the macro in `etc/add-log. return 0 and don't advance input pointer. * configure. from the GDB source tree. */ if (count > strlen (*type)) { .2MP and i[3456]86-*-sysv4. Even though this entry describes two changes to `configure.2uw2*. If you are using vi. not mach3. Here's an example of doing it right: 1999-02-23 Tom Tromey <tromey@cygnus. separated by blank lines. terser format. (i[3456]86-*-sysv5*): Recognize this. so we don't have to glean it from the individual changes.vi'.host (i[3456]86-*-sysv4. Each paragraph should be a set of changes that accomplish a single goal. alongside the code it explains. In this case we just consume until the end of the string.2v5*.1) that generates entries with more verbose dates. in `consume_count' in `cplus-dem. because they're unrelated changes. If you find yourself writing a significant explanation in the ChangeLog.com> * configure.cygnus. Use your best judgement --. count += **type . * configure. Attempt to sort out SCO-related configs.tgt'.2*): Use this instead of i[3456]86-*-sysv4. And then. there is a tension between making entries easy to find by searching for identifiers. Group ChangeLog entries into "paragraphs". i[3456]86-*-sco3.and be considerate of your fellow developers. The second change to `configure. they're in separate paragraphs.

[ch] (gdbarch_tdep. For example. as in this example (mostly real. Writing ChangeLog entries for merges -----------------------------------Revision management software like CVS can introduce some confusion when writing ChangeLog entries.all the details should be in the source. you wouldn't find that either.*type = save. and then merge it into the trunk months later. return 0. one might write a change on a branch. * CVS doesn't segregate log entries for branches from those for the trunk in any useful way. ChangeLogs and the CVS log -------------------------CVS maintains its own logs. and made a second pass looking for gdbarch. This makes it difficult for others to search the ChangeLog for changes to the file or function they are interested in.}gdbarch_long_bit. In that case. {set. but binds each entry to a specific revision. you would not find the above entry. so we maintain both. * CVS provides no easy way to see the changes made to a set of files in chronological order. it's difficult to pull together changes that cross several files. though. {set. When you commit a change. and write out the names. However. } This is why a new function. If you gave up.c.}gdbarch_ptr_bit): Corresponding functions. the CVS log is more useful than the ChangeLog.}gdbarch_long_long_bit. since it would simply duplicate the contents of the file itself. It is not necessary to provide CVS log entries for ChangeLog changes. For example. This duplicates the information present in the ChangeLog. which you can access using the `cvs log' command. because the writer used CSH-style globbing to abbreviate the list of functions. for example. needs only a log entry saying "New Function" --. * Unless you put full ChangeLog paragraphs in your CVS log entries. which can be helpful at times. but slightly exaggerated): * gdbarch. the CVS log is no substitute for the ChangeLog files. if you searched for `set_gdbarch_long_bit'. gdbarch_byte_order. In some circumstances. Avoid the temptation to abbreviate filenames or function names. you should provide appropriate text in both the ChangeLog and the CVS log. not by date. They're sorted first by filename.that of the original change. gdbarch_bfd_arch_info. what position and date should the developer use for the ChangeLog entry --. or the date of the merge? . Consider your poor readers. {set.

the entry for the merge should be like any other change --. For the merge entry. Remember that people looking for the merge will search for the original changelog text. we use the merge date. "Keith Seitz" is the original author of the change. inserted at the top of the ChangeLog and reflecting the date the change was committed to the branch (or trunk).cygnus.. and stamped with the date the merge was committed. because this is when the change appears on the trunk or branch this ChangeLog documents. It should indicate the origin of the change.com> [. so it's important to preserve it unchanged. This approach preserves the structure of the ChangeLog (entries appear in order. and dates reflect when they appeared). "Jim Blandy" is doing the merge on March 26. As shown here. the ChangeLog entry should be written as normal. or to another branch). and provide the full text of the original entry. the ChangeLog entry should have the following form: 1999-03-26 Jim Blandy <jimb@zwingli.inserted at the top of the ChangeLog. and not the original date. Its impact on these sources is independent of when or where it originated. . but also provides full information about changes' origins.] In this case.com> Merged change from foobar_20010401_branch: 1999-03-16 Keith Seitz <keiths@cygnus. who committed it to `foobar_20010401_branch' on March 16.The principles described at the top need to hold for both the original change and the merged change.. indented to avoid being confused with a true log entry. That is: * On the branch (or trunk) where the change is first committed. * When the change is then merged (to the trunk.