[Contents]   [Back]   [Prev]   [Up]   [Next]   [Forward]  

Writing ChangeLog entries for merges

Revision management software like CVS can introduce some confusion when writing ChangeLog entries. For example, one might write a change on a branch, and then merge it into the trunk months later. In that case, what position and date should the developer use for the ChangeLog entry -- that of the original change, or the date of the merge?

The principles described at the top need to hold for both the original change and the merged change. That is:

As shown here, the entry for the merge should be like any other change --- inserted at the top of the ChangeLog, and stamped with the date the merge was committed. It should indicate the origin of the change, and provide the full text of the original entry, indented to avoid being confused with a true log entry. Remember that people looking for the merge will search for the original changelog text, so it's important to preserve it unchanged.

For the merge entry, we use the merge date, and not the original date, because this is when the change appears on the trunk or branch this ChangeLog documents. Its impact on these sources is independent of when or where it originated.

This approach preserves the structure of the ChangeLog (entries appear in order, and dates reflect when they appeared), but also provides full information about changes' origins.

[Contents]   [Back]   [Prev]   [Up]   [Next]   [Forward]