Re: Writing changelog entries

[Stephen Leake <stephen_leake@acm.org>]

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