Introduction

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.