Re: Next GNUstep release

[Ivan Vučica]

Please also see the other thread for my thoughts so I don't repeat
them in detail, but just this:

On Mon, Apr 6, 2020 at 2:46 PM David Chisnall <address@hidden> wrote:
>  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).

If you carefully look into individual messages over the span of a year
with limited time to examine each change -- you are likely going to
share my experience of finding individual commits are very
non-detailed.

Should we enforce each commit to be larger before publishing? Should
we enforce commit chains to end up in a merge commit which is
detailed? Should we enforce updating changelog-equivalent only when a
particular feature is finished and ready to be added -- but *enforce
it consistently*?

Again, I don't want to have to have to distinguish between "this is
adding a new class", "this is fixing a security bug", "this is
*partially* addressing a security bug", "this is a quick compile fix",
"this is a large overhaul of the build system" by having to inspect
each commit in a really long chain of commits. Not necessarily a tree,
even.

FWIW ChangeLog entries *when written* were more useful for this
purpose. The problem was *when they weren't written*.

It's not necessarily true that the ChangeLog format is useful, but we
either need something like it, or we need to hold ourselves to strict
high standards of how we write commit messages, or we need cover
letters / detailed merge commits, or each new commit *must* have a
*tracking* bug ("issue") entry that we can use to write release news.

Git commits as written today are unsustainable.

> 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.

This is a nonsolution if git messages keep being to the tune of
"Actually fix the implementation" <-- which implementation? how? why?
what's getting fixed? what was broken in the first place?

ChangeLog, *when written*, have been less of a problem *during this
particular release timeframe*.

>
> >
> > 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.

Yes please. Let's do both. Let's write a note whenever you are halfway
or fully done with a new feature, whenever you fix a bug.

Enforce that commits, when merged, include this.

Whether you put it in news.texi, or write these notes in ChangeLog
(referencing exact files or not), or we keep release notes in a new
directory, with files named 'YYYY-MM-DD-NN' that we flush as part of
the release process, I don't care much.

But maintainers, please just decide something and proclaim that this
is what will be done. It doesn't have to be consistent among packages,
but *within* a particular release of an individual package, I'd like
to see consistency. We can't have some people "opt-out" of the chosen
process. Maintainers need to be the ones to enforce this, including
possibly writing the log entries ('blogposts'?) themselves.