Re: Using VC for change descriptions

[Joseph Myers]

On Mon, 15 Jan 2018, Richard Stallman wrote:

>   > I suggest looking at the glibc commit logs that already exist.  I and 
> many 
>   > other contributors already write the overall explanation of the changeset 
>   > as well as the ChangeLog entry (the ChangeLog entry then may or may not 
>   > also be included in the text of the commit message, but for this purpose 
>   > one would ignore it when trying to understand based on the commit 
> messages 
> 
> Would you please send me a sample to look at?  I will look at it.

I've attached the glibc logs since the last release (output of "git log 
glibc-2.26..HEAD").  The logs are very long, so you probably only want to 
look at a few samples.

(I don't actually think simply looking at example logs is a particularly 
useful experiment, since the best uses of logs are *active* - given some 
concrete issue with a package, working on that issue with reference to the 
version control history whenever that's useful.)

> But what exactly is the question you suggest I could answer
> by looking at it?

My comment was in reply to your "Then we can try understanding changes in 
two ways: based on change logs as we write them, and based on that 
rewritten history, and see whether it makes a big difference.".

So the point would be to try understanding changes based on these logs 
(minus the ChangeLog entries, where included in the logs), compared to 
understanding them using the ChangeLog entries as well (sometimes included 
in these logs, otherwise available in the glibc repository).

But in both cases I think that if you want to understand an individual 
change, the logs are best used together with the diffs themselves rather 
than in isolation.  So the question is something like: how easy is it to 
understand changes from the changeset-level logs plus diffs (minus 
ChangeLog entries), compared to attempting the same but with the ChangeLog 
entries available as well as the changeset-level logs and diffs?

(Some of the existing changeset-level descriptions may have insufficient 
information, or nothing beyond the ChangeLog entries.  If we allow GNU 
packages not to use ChangeLog format, it will be important for packages 
choosing not to use ChangeLog format to ensure that sufficiently detailed 
commit messages are used instead.  For some simple changes, just a summary 
line may be sufficient, but many will need more detailed descriptions.)

-- 
Joseph S. Myers
address@hidden

glibc-logs.gz
Description: application/gzip