Richard, On Mon, Apr 6, 2020 at 7:56 AM Richard Frith-Macdonald < rich...@frithmacdonald.me.uk> wrote:
> > > > On 6 Apr 2020, at 09:53, David Chisnall <gnus...@theravensnest.org> > wrote: > > > > I second that, thank you Ivan, but Fred your proposed solution is going > to add more barriers to entry. > > > > ChangeLog files made sense when people were submitting patches on the > mailing list and distributing code in tarballs. > > > > They were slightly anachronistic when CVS became standard for F/OSS > projects and incorporated per-file change messages but they were still > useful when people used them to describe the relationship between changes > in multiple files. > > > > They were mostly obsolete when projects moved to svn and commits became > atomic. Commit messages then referred to a set of related changes, rather > than to single files. The one remaining argument for them was that VCS > history may get lost in moves between revision control systems. > > > > There was also a minor justification for them based on tooling: commit > messages for svn were written after code review and some tools did not > support reviewing the commit message along with the code (things like > Phabricator did), so you could enforce a ChangeLog message in code review > but you could not enforce a commit message at the same time. > > > > We have now seen projects move from CVS to SVN and then to Git, > preserving commit messages. Git commits have evolved a structure that is > well supported by a load of tooling (vim even gives nice syntax > highlighting to ensure that you confirm to this structure, all of the Git > GUIs, including GitHub, are designed to render it), where the first line is > short and gives a very high-level summary of the changes and the remainder > gives a detailed overview. No equivalent tooling exists for ChangeLog files. > > > > In addition, a branch-and-PR workflow makes it possible to do code > review of commit messages before merging. Git makes it easy to edit and > amend commit messages and force-push a branch, so individual commits can > have their messages edited before a branch is merged. > > > > I would much rather see code review enforcing good commit messages, > which is a workflow that contributors to any other open source project will > be familiar with. I fail to see any benefit in having ChangeLog entries. > > > > Note: I *do* see a benefit in having a separate NEWS or ANNOUNCE file > that captures high-level user-visible improvements. We don't necessarily > need PR authors to write that, but the person merging a PR probably should > if not. This is far less granular than a commit message and serves a > separate purpose. > > > > David > > Yes, thanks to Ivan. > > I have spent some time thinking about this, and while in the past I've > argued against dropping ChangeLog (it's more convenient than the git logs, > and of course is there for peple who download tarballs etc and don't have > ready access to the repositories), but I think overall I kind of agree now. > > It's very onerous to put comments in multiple places, but there is value > to each of these things: > Technical information in the repository > ChangeLog for easier access > Announce/News for summary of important details. > > What I'd like to suggest is sort-of (but not entirely) scrapping > ChangeLog, in that we could auto-generate ChangeLog entries from the > repository, either by an automated commit hook or (assuming that's not easy > to do readily), using a script to get details from the repository just > before we make a realease, so that anyone getting a release of the software > still gets a comprehensive ChangeLog. > > Then we would be saved the overhead of writing ChangeLog entries and could > concentrate on: > 1. meaningful commit entries, which of course we should all be doing > anyway ;-) > 2. writing release notes for any substantive change (rather than ChangeLog > entries for even minor changes), to appear in the NEWS when we make a > release > > If we stop writing ChangeLog entries, we should be able to write release > notes and still be spending less time, and of course that would make the > process of cutting a release less onerous. > > Does this seem a reasonable approach? > > I believe this is entirely reasonable. -- Gregory Casamento GNUstep Lead Developer / OLC, Principal Consultant http://www.gnustep.org - http://heronsperch.blogspot.com https://www.patreon.com/bePatron?u=352392 - Become a Patron
