Re: Using VC for change descriptions

[Joseph Myers]

On Mon, 27 Nov 2017, Richard Stallman wrote:

> If that is true, it is a good method.  Would someone like to determine
> what rules people should practice, so as to assure that the output gives us
> all the useful information that a properly written ChangeLog file has?
> (It doesn't need to be the same in form.)

Once you're no longer using the ChangeLog format, I'd say: describe the 
change at the logical level appropriate for the change - that's vague, but 
it's hard to define more precisely what's appropriate in all cases.  
Sometimes a single summary line suffices for a simple change.  Sometimes 
there may be several paragraphs to explain what is being changed.  This 
text may or may not name individual files and functions being changed, 
depending on whether doing so is useful for someone seeking to understand 
the change as a whole.  (For example, if there's something non-obvious 
about how or why a particular piece of code is being changed in the patch, 
you may wish to note it individually.  If a similar group of changes are 
being made in many places, you probably don't want to name the individual 
files and functions being changed unless there's something special about a 
particular case.)

This does mean the logs may not always mention a file or function being 
changed, but the times they do mention a change are more likely to be 
significant ones rather than a mechanical change applied globally.  (When 
looking at logs for a file in GCC, I sometimes find a significant 
proportion of the commits are actually global changes that just happened 
to touch that file along with many others - and such commits are rarely 
relevant for whatever issue I'm working on.)

-- 
Joseph S. Myers
address@hidden