|
| From: | Gregory Casamento |
| Subject: | Re: Next GNUstep release |
| Date: | Mon, 6 Apr 2020 09:40:03 -0400 |
> On 6 Apr 2020, at 09:53, David Chisnall <address@hidden> 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?
| [Prev in Thread] | Current Thread | [Next in Thread] |