Re: Using VC for change descriptions

[Joseph Myers]

I would like to restart the discussion of use of the version control 
history of a project, with descriptions of changes at the level of the 
complete changeset rather than necessarily at the level of changes to 
individual files and functions (depending on what seems appropriate for 
each individual change, but written on the assumption that the reader has 
access to the actual patch in the version control history so not needing 
to describe every physical change in the patch in detail), as an 
alternative to the use of ChangeLog format.

Specifically, I suggest that we consider Paul Eggert's patch of 3 August, 
as attached to 
<https://lists.gnu.org/archive/html/bug-standards/2017-08/msg00005.html>, 
as a starting point for such a change to the GNU Coding Standards.

In any case, the proposal (a) is for an alternative to use of ChangeLog 
format, without requiring any projects to change if they don't wish to, 
and (b) does not remove any existing requirements for comments in code 
that are relevant to understanding why it does certain things.  Existing 
ChangeLog files would also be kept if covering periods where the commit 
history does not have adequate per-changeset descriptions.

The previous discussion started with 
<https://lists.gnu.org/archive/html/bug-standards/2017-07/msg00000.html> 
and continued into August.  As I understand the main issues raised by 
people with concerns about the proposal:

* Some people currently use ChangeLogs while understanding changes to a 
project and would need to start using a different workflow if that project 
moved away from ChangeLog format.  I believe all the main use cases are 
adequately covered through use of distributed version control tools (for 
example, "git log" options such as -L for listing changes to a particular 
function or other identified region of code), so this is just a matter of 
changing how one investigates past changes to a project when working on it 
(and the change would only be made for a particular project if it's what 
that project's maintainers / developers want); ChangeLog format does not 
add anything significant when a project uses commit messages describing 
each change at an appropriate level for that change.

* There were questions about providing change history information in 
release tarballs, and about ensuring the version control history remains 
available long-term.  Whether the information is in release tarballs is 
not part of my proposal, but I don't think it should need to be there 
(beyond the NEWS file contents); I think it's reasonable to expect people 
wanting to look at details of every individual change made during 
development to look at the public version control system.  As for ensuring 
the version control history remains available, there is much less risk of 
it being lost when using a distributed version control system, when every 
checkout has a copy of the full history, than with a centralized system 
where there may only be one copy of the full history.  While it might make 
sense for Savannah to have a service for mirroring version control history 
of GNU projects keeping their main repositories elsewhere, the Savannah 
admins are very busy and I don't think it makes sense for such a service 
to be a dependency of changing the requirements for how changes to GNU 
software are logged.

-- 
Joseph S. Myers
address@hidden