Re: Using VC for change descriptions

[Mathieu Lirzin]

Hello,

Joseph Myers <address@hidden> writes:

> Indeed.  We know that in practice distributed VCS history is a suitable 
> substitute for ChangeLog files, including (from experience with non-GNU 
> projects) when that history is not in ChangeLog format.
>
> It is also clear in practice that there are certain kinds of changes for 
> which the ChangeLog format is poorly suited, because those changes cannot 
> readily be described or understood in terms of separate descriptions of 
> what they do to each individual named entity affected, or because 
> describing in those terms results in a very long description that is 
> excessively duplicative of the diffs themselves (which can be seen in the 
> VCS history).  In such a case, a good, higher-level description of the 
> changes is needed - but adding the ChangeLog-format descriptions of each 
> fragment of the changes is extra work that does not provide any 
> corresponding benefit.  This is why I think we should stop requiring use 
> of ChangeLog format.  (The standards already allow automatic ChangeLog 
> file generation from version control history; the issue is with the 
> format.)

Even If I personnally like the fact that using the ChangeLog format in a
commit message is a way to take some time to review your own commit by
summarizing the diffs and briefly describing the links between each
function/file change, I agree that the benefit of the changelog format
can be small for some developpers.

Regarding the overall benefit of it, I think you miss the point that VCS
history (containing the diffs) is not distributed with the tarballs.
For the users the NEWS and ChangeLog files are their easiest way to
understand why a function doesn't act as it previously does or a file
doesn't exist anymore when testing a new release.  So IMO the benefit is
for the users not the maintainers.

Having said that we could consider that the maintainer effort doesn't
worse the benefit of not requiring the user to download the whole VCS
repository (which can be huge with DVCS) even for small investigations.

-- 
Mathieu Lirzin
GPG: F2A3 8D7E EB2B 6640 5761  070D 0ADE E100 9460 4D37