Writing changelog entries

Writing changelog entries

[Florian Weimer]

How are you writing your changelog entries?

There are a few Ada-specific questions.  Shall I include the package
name, or is the file name enough?  How does one deal with homonyms?

Here's an example, but I'm not completely satisfied with it.  Then
again, I don't use changelogs much because I wrote most of the code
pretty recent and it's still a small project (by Ada's standard, not
necessarily by mine).

----------------------------------------------------------------------
r762:  fw | 2005-01-04 21:26:27 +0100

* lib/core/enyo-io.ads, lib/core/enyo-io.adb (Put):
  New procedure which copies data from one buffer to another.

* lib/core/enyo-io-file_queues.ads, lib/core/enyo-io-file_queues.adb
  (Write): Rename to Put.
  (Put): New procedure which copies the contents of a buffer.

* test/tests-io-channels.adb, test/tests-io.adb:
  Adjust old Put calls.

* test/tests-io-file_queues.adb:
  Adjust old Write calls.  New test case for Put of a buffer.

Re: Writing changelog entries

[Randy Brukardt]

"Florian Weimer" <fw@deneb.enyo.de> wrote in message
news:87y8f96imj.fsf@deneb.enyo.de...
> How are you writing your changelog entries?

Change log entries for what? The answers vary depending on the purpose. I
generally put brief notes into the source code ("Edit History") and the VCS,
and that's it. For user-level lists of feature changes, I make general
descriptions of the change. So I guess I rarely use package names or any of
that sort of level stuff in my comments. If I need it again, I can get it
from the VCS diffs and change lists -- the notes usually are for that
purpose -- and using a tool is always preferable to anything created by
hand. Of course, if there is anything "interesting", I put lots of comments
in at the locus of the change - so I'll see them the next time I'm working
in that area.

                             Randy.

Re: Writing changelog entries

[Stephen Leake]

Florian Weimer <fw@deneb.enyo.de> writes:

> How are you writing your changelog entries?

This is probably highly project specific, but I'll give you what I do.

I just use Emacs and CVS, and then when I do a release, I use
cvs2cl.pl (http://www.red-bean.com/cvs2cl/) to generate a changelog.

-- 
-- Stephe

Re: Writing changelog entries

[Florian Weimer]

* Stephen Leake:

> Florian Weimer <fw@deneb.enyo.de> writes:
>
>> How are you writing your changelog entries?
>
> This is probably highly project specific, but I'll give you what I do.
>
> I just use Emacs and CVS, and then when I do a release, I use
> cvs2cl.pl (http://www.red-bean.com/cvs2cl/) to generate a changelog.

Generating the changelog is not the problem.  It's the format of the
entries in it.  Many projects have explicit guidelines which ensure
that you can grep the changelog and find the change which affected a
particular entity.  However, these guidelines are C-specific and do
not take homographs into account (and neither nested subprograms, and
so on).

Re: Writing changelog entries

[Stephen Leake]

Florian Weimer <fw@deneb.enyo.de> writes:

> Many projects have explicit guidelines which ensure that you can
> grep the changelog and find the change which affected a particular
> entity. 

I never use a changelog for that. In fact, I never do that. But I
guess I haven't been involved in a large project where that would be
necessary; all my projects are small enough that I know what's going
on anyway, by keeping up with daily CVS updates.

> However, these guidelines are C-specific and do not take homographs
> into account (and neither nested subprograms, and so on).

Right. Hmm. You want a CM tool that can answer the query:

    what changes affected <name>.

I don't know of any CM tools that do that directly; it would require
the CM tool to understand the language.

In Ada, every name can be spelled uniquely; for overloaded functions
you need to include the parameter/result profile, etc. So you could
have a style guide that says "when checking in changes, include the
_unique_ name of every item affected". Yuck; that would be a huge
burden on the programmers. 

You could write an ASIS tool to generate that name list by comparing
the two versions of the file; you can have CVS run that tool and
append the result to the checkin comment. Hmm. Getting both versions
into one ASIS context would be tricky; you'd need a top level
namespace for each version. Whether that's worth doing depends on how
often you do this query, and how important it is.

Hmm. You could have the CM tool generate the diffs for each change,
and then grep that for <name>. That might be efficient, but it doesn't
address the homograph issue.

-- 
-- Stephe

Re: Writing changelog entries

[Pascal Obry]

Stephen Leake <stephen_leake@acm.org> writes:

> I just use Emacs and CVS, and then when I do a release, I use
> cvs2cl.pl (http://www.red-bean.com/cvs2cl/) to generate a changelog.

I do the opposite. Using PCL-CVS (as you :) I use the shift-A key on the
modified file in the PCL-CVS *cvs* buffer. This open the right ChangeLog file
(in the current directory or in the parent one) and I edit the revision
history there. I do that for all files to commit. Then when ready I do a
shift-C on each files. The last step is to commit the ChangeLog file itself.

Pascal.

-- 

--|------------------------------------------------------
--| Pascal Obry                           Team-Ada Member
--| 45, rue Gabriel Peri - 78114 Magny Les Hameaux FRANCE
--|------------------------------------------------------
--|              http://www.obry.org
--| "The best way to travel is by means of imagination"
--|
--| gpg --keyserver wwwkeys.pgp.net --recv-key C1082595

Re: Writing changelog entries

[Stephen Leake]

Pascal Obry <pascal@obry.org> writes:

> Stephen Leake <stephen_leake@acm.org> writes:
> 
> > I just use Emacs and CVS, and then when I do a release, I use
> > cvs2cl.pl (http://www.red-bean.com/cvs2cl/) to generate a changelog.
> 
> I do the opposite. Using PCL-CVS (as you :) I use the shift-A key on the
> modified file in the PCL-CVS *cvs* buffer. This open the right ChangeLog file
> (in the current directory or in the parent one) and I edit the revision
> history there. I do that for all files to commit. Then when ready I do a
> shift-C on each files. 

Does that read the Changelog file and use the comment for the commit?
Or is the CVS commit comment left empty?

-- 
-- Stephe

Re: Writing changelog entries

[Pascal Obry]

Stephen Leake <stephen_leake@acm.org> writes:

> Does that read the Changelog file and use the comment for the commit?

Yes that does all the work for you. You just need to do a ctrl-c/ctrl-c

Magic :)

Pascal.

-- 

--|------------------------------------------------------
--| Pascal Obry                           Team-Ada Member
--| 45, rue Gabriel Peri - 78114 Magny Les Hameaux FRANCE
--|------------------------------------------------------
--|              http://www.obry.org
--| "The best way to travel is by means of imagination"
--|
--| gpg --keyserver wwwkeys.pgp.net --recv-key C1082595

Re: Writing changelog entries

[Randy Brukardt]

"Florian Weimer" <fw@deneb.enyo.de> wrote in message
news:87wtus3do0.fsf@deneb.enyo.de...
> Generating the changelog is not the problem.  It's the format of the
> entries in it.  Many projects have explicit guidelines which ensure
> that you can grep the changelog and find the change which affected a
> particular entity.  However, these guidelines are C-specific and do
> not take homographs into account (and neither nested subprograms, and
> so on).

My personal opinion is that that is not worth it. Changes should have been
at least minimally tested before being checked it, and if they cause a
regression test to fail, they should be fixed immediately while the
programmer still remembers what he did. (They then won't need to work back
through the system.)

That leaves the rare cases where a problem shows up much later. In those
cases, it's usually necessary to debug the entire thing again anyway. So,
leaving comments in the place where the code is the most valuable, because
it's where you're going to be looking anyway.

If it takes two extra minutes (probably conservative) to create structured
changelogs, you'd have to save more than 4 hours of development time to come
out ahead on the 1 out of 100 (probably pessimistic) changes that you have
go back and debug in the future. While that's possible, it seems unlikely.
Just having the CM (with no changelog at all) seems to save most of the
time; I do try to put the bug report number into the code and/or edit
history (presuming it is formally tracked; we only do that for outside bug
reports, because of the time investment), which helps find the change again
if needed.

                    Randy.

Re: Writing changelog entries

[Brian May]

>>>>> "Randy" == Randy Brukardt <randy@rrsoftware.com> writes:

    Randy> That leaves the rare cases where a problem shows up much
    Randy> later. In those cases, it's usually necessary to debug the
    Randy> entire thing again anyway. So, leaving comments in the
    Randy> place where the code is the most valuable, because it's
    Randy> where you're going to be looking anyway.

Then you come to a line of code that is causing problems.

You can't remember why the line was in its current form (probably a
mistake, and you change it to what looks correct.

Months later you observe a different problem. You change the same line
of code back to the original value, because you can't remember why you
changed it before, and it looked totally wrong before.

Months later you observe the original problem again. After hours of
debugging, you end up changing the same line of code back to the
modified value, because you can't remember why you changed it before,
and it looked totally wrong before.

...repeat...

See a pattern here?

Meanwhile, the real bug is not getting fixed.

You should be documenting *why* changes are made so you don't have to
reinvent the wheel every time you encounter the same problem again.

Comments in the code only really describe what the code does (or more
precisely: what it is meant to do), not why a change was made. Yes,
you could document a complete history of why you made every change as
comments in the source code, a changelog file would appear to be
better suited for the purpose though.

Also, a good changelog is required if you want to upgrade numerous
systems, and want some idea of what is likely to break in the upgrade.

Not to mention security related issues. A good changelog may help
identify what versions of the software had a serious security bug for
instance.
-- 
Brian May <bam@snoopy.apana.org.au>

Re: Writing changelog entries

[Stephen Leake]

Brian May <bam@snoopy.apana.org.au> writes:

> You should be documenting *why* changes are made so you don't have to
> reinvent the wheel every time you encounter the same problem again.

If you document why the code is the way it is, _and_ why it is not
some other way that you considered, you can terminate the perpetual
changes. 

Such documentation belongs in the code as comments if it is short
enough, or in a separate design document, with a reference in the
code. 

> Comments in the code only really describe what the code does (or
> more precisely: what it is meant to do), not why a change was made.
> Yes, you could document a complete history of why you made every
> change as comments in the source code, a changelog file would appear
> to be better suited for the purpose though.

Change logs are not design documents.

-- 
-- Stephe

Re: Writing changelog entries

[Randy Brukardt]

"Brian May" <bam@snoopy.apana.org.au> wrote in message
news:sa48y74n7bq.fsf@snoopy.apana.org.au...
> >>>>> "Randy" == Randy Brukardt <randy@rrsoftware.com> writes:
>
>     Randy> That leaves the rare cases where a problem shows up much
>     Randy> later. In those cases, it's usually necessary to debug the
>     Randy> entire thing again anyway. So, leaving comments in the
>     Randy> place where the code is the most valuable, because it's
>     Randy> where you're going to be looking anyway.
>
> Then you come to a line of code that is causing problems.
>
> You can't remember why the line was in its current form (probably a
> mistake, and you change it to what looks correct.

The code should be commented as to why it is the way currently is. Of
course, that isn't always done (when it appears obvious). But if a bug
report causes a change, usually I'll include the bug report number and an
explanation of why the code needs to be the way it is.

> Months later you observe a different problem. You change the same line
> of code back to the original value, because you can't remember why you
> changed it before, and it looked totally wrong before.

Well, unless I've lost the ability to read comments, that's not likely to be
an issue. Moreover, I would be remiss if I don't use the bug report number
to look up the associated regression test to insure that I didn't
reintroduce a bug.

> Months later you observe the original problem again. After hours of
> debugging, you end up changing the same line of code back to the
> modified value, because you can't remember why you changed it before,
> and it looked totally wrong before.

Couldn't happen: even if I didn't manually check for a regression, the
regression tests (which are run very often - usually immediately after a
change) would have caught the problem. For this to happen, I've have to have
failed to comment the code *and* failed to create a regression test. I'd
fire myself if I did that!

> ...repeat...
>
> See a pattern here?

Sure; some people neither create tests nor properly comment their code. What
good would a changelog do? It's widely separated from the code in question;
I don't want to have to look in a half dozen places to understand some code!
And if people aren't putting in useful comments or creating tests, why would
they write a useful changelog?? (Certainly, if I didn't do the first two
because I was in too much of hurry, the third will be even more useless...)

> Meanwhile, the real bug is not getting fixed.
>
> You should be documenting *why* changes are made so you don't have to
> reinvent the wheel every time you encounter the same problem again.

Absolutely. At the place of the bug, in the code where you can't help but
see it the next time your debugging path leads you there.

> Comments in the code only really describe what the code does (or more
> precisely: what it is meant to do), not why a change was made.

Those would be pretty useless comments. The only comments that *are* useful
are those that explain *why* code is the way it is. The other questions
(what, where) usually can be answered by reading the code itself.

> Yes, you could document a complete history of why you made every change as
> comments in the source code, a changelog file would appear to be
> better suited for the purpose though.

I don't see why; it's widely separated from the code in question. There is
no sane way to associate the descriptions with the code -- and that's what
you need to understand the code and avoid reintroducing problems.

I don't believe in separate design documents (other than for "big picture"
sorts of descriptions), either.

> Also, a good changelog is required if you want to upgrade numerous
> systems, and want some idea of what is likely to break in the upgrade.

We always tried to keep the systems maintained in parallel. Traditional
source code control systems do a lousy job of this, and we wrote our own
tools to manage the files (most of them are shared between the versions,
only a few need manual upgrades).

But I realize that won't work everywhere.

> Not to mention security related issues. A good changelog may help
> identify what versions of the software had a serious security bug for
> instance.

That seems like a job for a bug tracking database. We've never computerized
that (I still use the paper-based system we worked out in the 80s), but it
would be easy enough to do.

I don't want to claim that the changelog has no use whatsoever, but I don't
think there is much point to getting fancy with it. There are better places
for virtually all of the information that could be in it; you just need
enough to insure that you can find a particular change in the rare case that
you need to see how you got to the current code.

                            Randy.