On Sun, 6 Aug 2017, Alfred M. Szmidt wrote: > > ChangeLog entries are trivial and quick to write, and save so much > > This whole proposal is because they are not at all trivial or quick to > write for the sorts of changes that are common in projects such as glibc > or GCC, which are very different from the small local changes illustrated > in the example ChangeLog entries in the GNU Coding Standards. > > Then we should look into ways to make them quicker for these cases > instead of throwing out the baby with the bath water. I showed an > example on how they are easy and quick to write for changes that > affect many similar files, still using the current way of writing > them. If you can show how they are complicated maybe this dicussion > can be turned into something a bit more interesting?
I don't think your example was an improvement, either in usefulness of the content or ease of writing it. I think that just about any patch to GCC or glibc whose ChangeLog entry is over 10 lines is a case where, given a good changeset-level description of the patch (which may or may not refer to individual files and functions, depending on what is helpful in that context - but in any case, should be written on the basis that the reader has access to the patch itself if they are interested in more details, and the commit message just needs to provide an overall guide to the patch with enough information for someone to decide whether to look at the patch itself), and given universal access to the version control history, the utility of a ChangeLog-format description is negative: the time required to produce a description split up at that level outweighs any benefits from any information therein that is not in the changeset-level description and is not simply a function of the diffs that could be generated automatically at the time of use. As I've said, I don't object to shipping the changeset-level descriptions (e.g. the output of git log --stat) in tarballs, although I don't actually consider that particularly useful. Or to having separate -with-history tarballs to archive the VCS history at the time of a release. > If ChangeLogs isolate the GNU project some how, I don't know nor is it > very relevant, it just moves the discussion from if they are useful or > not to hypothetical speculation as to what people might or might not > think about topics that can't be quantified. The GNU Coding Standards should reflect good practice for the future free software environment, not the past. Once they were ahead of their time, with principles such as avoiding the arbitrary limits that were common in the Unix tools of the time. Now, ChangeLogs are behind current practice. We should *mandate* public version control. We should *mandate* preserving the history if converting between version control systems. We should *mandate* development discussions and bug tracking being public and archived. All of those have been established good practice for a long time (and the GNU project provides hosting resources in the form of savannah for GNU packages needing such resources). And we should recognize that with a DVCS, there is a better undo list of changes to the code than any ChangeLog could possibly provide. > Linux is also a poor example to highlight how ChangeLog might > hypothetically impede a project seeing that the maintainer is activley > hostile towards our goals, and that Linux includes non-free software > and why we have Linux-Libre Linux is an excellent example when working on glibc at the kernel/userspace interface, where it's normal for changes involving a new syscall or other kernel interface to require work on both the kernel and glibc sides of the boundary and it ought to be easy for the same person to do the related work on both sides without unnecessary hoops to jump through - and the syscall interfaces in question don't involve any non-free software. This is fundamentally different from e.g. code formatting where the different choices are both reasonable in current practice. -- Joseph S. Myers [email protected]
