[En-Nut-Discussion] ChangeLog (was Nut/OS 4.9.6 Beta)

[Harald Kipp]

Hi Ulrich,

Ulrich Prinz wrote:

> Some files really where changed and yes, I'll add some comments next time.

Wrong ChangeLog. Obviously some explanations are required, may be
discussions also.

Until March 2009 we used ChangeLog to provide an easy to read overview
of all the changes. Furthermore we used the CVS keyword $Log$ to
automatically add the commit comments to the modified files.

This was most convenient for the reviewer, because each file contains a
history on top and the ChangeLog provides a complete overview. The other
side of the coin was, that the developer has to write comments for the
commit and additionally has to write a nice text in ChangeLog as well,
listing all the files that had been involved in a certain change.

Example:

2009-02-16  Harald Kipp  <spamrobot at ethernet-mp3.de>

* include/arch/arm/at91_pmc.h, include/arch/arm/at91sam9xe.h:
Check for PLL B availability instead of target names.

One reason for changing from CVS to SVN was, that listing of files in
ChangeLog won't be required, because SVN revisions are atomic. I have to
admit, that I didn't understand that argument. And, because I didn't
understand, I did it wrong too in the past.

In order to make good use of atomic revisions, it is mandatory to fix
one problem after the other and commit each fix after the other. To give
a hypothetical example: Handshakes are not working on AT91 UARTs. As you
are working on these files already, you may also want to include DBGU
support in the AT91 UART driver. This should be done one after the
other. First, fix the handshake problem and commit all modified files.
Then add DBGU support and commit that one. This way the SVN history will
clearly list the fixes, enhancements etc. together with all files involved.

This way the SVN history will provide an acceptable replacement for the
ChangeLog file. It has the same contents.

Nevertheless, the Ethernut community got used to reading ChangeLog and
asked to continue it. While there is no need to list all modified files,
people would still like to have an easy to read comment like "I added a
new LED driver, which I tested on Atmel's SAM7X_EK".

Therefore I renamed ChangeLog to ChangeLog20090309 to freeze the CVS
version. Next I created a new ChangeLog, using a new format and adding
the request "What do you think about it?". Developers accepted it
without comment. The idea of the new format was to collect all
modifications under the 3 topics Fixed, Changed and Added for the user
who will upgrade to a new release. Frankly, I'm not satisfied with the
new format. It is difficult to read and less useful than the old
ChangeLog when searching for specific changes. And I'm not sure any
longer whether maintaining ChangeLog makes sense at all.

I don't see any reason, why the same comments in ChangeLog can't be used
in the commit as well. Specifically if we follow the strict rule to do
one modification after the other, as explained above. Initially I
expected to use this ChangeLog to provide a good summary for the casual
user. But look at it yourself. Does it really fit?

Long post, but it's nearly done. ;-) SVN no longer supports the keyword
$Log$, so there will be no history inside the files anymore. The history
may become misleading, if no longer updated. From time to time I already
replaced $Log$ by $Id$ in several source files, removing this old
history. Nothing is lost, because SVN took over the CVS history.
Recently I noticed, that some developers manually added these entries. I
do not think that this is a good idea, because it won't provide a good
history unless every developers maintains it.

More about $Log$:
http://subversion.tigris.org/faq.html#log-in-source

Thanks,

Harald