Re: Next GNUstep release

[David Chisnall]

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