Re: How much explanation to include in change descriptions

[Joseph Myers]

On Tue, 16 Jan 2018, Paul Eggert wrote:

> 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.

*But* it's also the case that the bug report may well contain discussion 
of ideas for fixes or speculation about the cause that's not actually 
relevant to the final fix.  In such cases, it's very helpful for the 
developer fixing the bug to write up a description of only those parts 
that are relevant, omitting all the false trails and other ideas.

In some cases, the description in the original bug report can be reused in 
the commit message - that's what I often do when fixing bugs I reported 
myself.

-- 
Joseph S. Myers
address@hidden