On 06/04/2020 12:56, Richard Frith-Macdonald wrote:
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.
I think that the place I'd disagree is that the ChangeLog is easier.
That was probably true with GNA, somewhat true with viewvc (though
debatable), but it isn't true with modern Git toolking (GitHub, GitLab,
GOGS and so on). Compare these two pages:
The ChangeLog file:
https://github.com/gnustep/libs-base/blob/master/ChangeLog
The Git history:
https://github.com/gnustep/libs-base/commits/master
The second is easier to skim, easier to jump to exact changes, and
easier to use to isolate change in a particular area (only care about
changes in the tools? Look here:
https://github.com/gnustep/libs-base/commits/master/Tools instead of the
main history page).
The ChangeLog is more useable only for people who don't have web access
(even if you download the tarball, you can still go to the web site to
view the history and if you've done a git clone then you can view and
search it offline easily). The last of those is actually a valid reason
for svn ChangeLog files that I missed: with svn, svn log was an online
operation, so you couldn't do svn log / svn blame without a network
connection, but you could read a ChangeLog. With git, that is not a
concern because log / blame are offline operations.
In terms of generating the ChangeLog entries automatically: I used to do
this when we used svn. I had a little script that would take an svn log
and write a ChangeLog entry. I didn't write the script, and when I
looked no one had written a version that worked with Git. I take this
to mean that there is very little perceived requirement for ChangeLog
files. Having a non-canonical copy of information that has a canonical
home doesn't seem valuable. If people want it, then they can do a git
log > MyOwnChangeLog.
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
The second of these is the difficult bit, but it's *incredibly*
valuable. For the runtime, I try to update the ANNOUNCE doc as I go,
but I still end up having to skim the git logs to check if I missed
anything. LLVM and FreeBSD both end up with manual steps and chasing
contributors to update these just prior to release (FreeBSD has a
'Release-Notes: Yes' thing you can put in the commit message so that the
release engineer will look at it for things to put in release notes).
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?
+1.
David