Re: How much explanation to include in change descriptions

[Paul Eggert]

Richard Stallman wrote:
>    > > It is useful to include a reference to the bug data base.
>    > > But don't omit anything on the assumption that people have access to
>    > > that data base.
>
>    > That's asking for too much, and in practice developers typically don't do 
> what's
>    > being asked for. Many bug reports are complex, and one must read them 
> carefully
>    > to understand the bugs. We can't reasonably ask developers to write and 
> read
>    > commit messages containing every detail of every report of a bug that was 
> fixed.
>    > On the contrary: the GNU bug database is a useful tool for simplifying
>    > maintenance, and we should take advantage of it when that is a win.
>
> I don't follow the response -- I have a feeling we are
> miscommunicating somehow.

I interpreted your advice to mean that every detail of a bug report that could 
ever possibly be of interest to a maintainer should be described or explained in 
the ChangeLog entry (or commit message) for its fix. This would cause ChangeLogs 
to contain clutter that is likely to cause more trouble than it's worth. Commit 
messages should focus on why the change was made; if this focus is aided by 
citing a bug number rather than listing only-mildly-relevant details about the 
bug, then that is a win.