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 [email protected]
