Re: Emacs 28.2 released

[Karl Fogel]

On 15 Sep 2022, Eli Zaretskii wrote:
> > From: Karl Fogel <kfogel@red-bean.com>
> > Cc: stefankangas@gmail.com,  emacs-devel@gnu.org
> > Date: Wed, 14 Sep 2022 14:53:43 -0500
> >
> > >> We have an entry in NEWS for 28.2.
> > >> 
> > >> That entry has a substantive item about an installation 
> > >> change. 
> > >> There are also a couple of items listed under "Changes in 
> > >> Specialized Modes and Packages in Emacs 28.2" (although one 
> > >> of 
> > >> them says that the change was actually released in 28.1 and 
> > >> that 
> > >> we just forgot to include it in the release notes then).
> > >
> > >These are not the bugfixes whose list you wanted to see.
> >
> > Sure it is.  It's good enough -- and presumably that's why we 
> > link 
> > to it from the 28.2 section on 
> > https://www.gnu.org/savannah-checkouts/gnu/emacs/emacs.html#Releases 
> > .
>
> Are we talking about the email announcements or are we talking 
> about
> the Emacs Web page?  They are two different media, and I thought 
> you
> were talking about the former.

We're talking about making a change to email announcements.

The fact that we already link to the minor release's NEWS file 
from the "#Releases" section of the web site indicates that we 
think the contents of those NEWS files to be noteworthy for the 
release.  We're already using them, effectively, as release notes 
-- they are, after all, notes about the release, that we link to 
from our web page about releases.  (I could have been clearer 
about the fact that I was using "release notes" as a shorthand 
phrase to refer this information that we already post to the web 
to accompany a release.)

> The email announcement of a major release (in this case, Emacs 
> 28.1)
> has this text:
>
>  For a summary of changes in Emacs 28.1, see the etc/NEWS file 
>  in the
>  tarball; you can view it from Emacs by typing 'C-h n', or by 
>  clicking
>  Help->Emacs News from the menu bar.
>
>  For the complete list of changes and the people who made them, 
>  see the
>  various ChangeLog files in the source distribution.  For a 
>  summary of
>  all the people who have contributed to Emacs, see the 
>  etc/AUTHORS
>  file.
>
> AFAIU, you wanted to have there an HTML link to the NEWS file, is 
> that
> correct?  If so, I can suggest adding to the above text the link 
> to
>
>  https://git.savannah.gnu.org/cgit/emacs.git/tree/etc/NEWS?h=emacs-28
>
> Would that be okay?

Yes.

There have been separate followup discussions here of improving 
the in-browser presentation of that information, and/or making the 
URL something a little more familiar, and those would be welcome 
improvements, but just doing the above would solve the problem -- 
we would now have a clickable link.

> One subtle issue here is that when we post the email announcement
> about a new release, the on-line manuals and the Emacs Web page 
> are
> not yet up-to-date, so either a link to anything inside the Web 
> pages
> will be outdated, or we will need to delay the announcement until 
> the
> Web pages are updated, both of which are undesirable.  A link to 
> Git
> above is thus a compromise that doesn't have these disadvantages.

I didn't know about that process ordering issue.  In that case, a 
simple solution is just a link to Git, as you suggest.

> > All I'm saying is that the announcement email should contain 
> > the 
> > *same link* that the above page contains.
>
> See above: that'd delay the release announcement, sometimes by 
> days,
> depending on the free time of the people who do these updating 
> jobs.

Yup; I didn't know about that ordering issue.  But a link to the 
exact same information (at this different, Git-based URL) is fine.

> > While the blurb for 28.2 may not be a complete list of 
> > bugfixes, 
> > it is still useful, both in what it contains and in its 
> > position 
> > at the end of an easily-navigable long line of past release 
> > notes.
>
> As explained already, that blurb is not a list of bugfixes at 
> all.  It
> is a list of noteworthy changes in the release, and in minor 
> releases
> it is usually very short, sometimes includes "old news" from the
> previous releases that we just forgot to mention, and could even 
> be
> empty.  I don't especially mind having that referenced in the 
> email
> announcements, but if that satisfies your request, I really 
> wonder
> what was all the fuss about.

"A list of noteworthy changes in the release" sounds like a 
description of release notes, and is good enough.  If some day we 
have a chance to make even more information easily available, 
that's even better, but no need to wait for that.

> If by "release notes" you mean the NEWS file, this can be done,
> although I question the usefulness.

I assumed that if we are maintaining the NEWS file entries, we 
must think they are useful news.  Otherwise, why are we writing 
them?

> If you mean something else, then
> we don't have any "release notes" in Emacs; however the Emacs Web 
> page
> does show a list of the more important new features in each major
> release.
>
> > That single link is enough to satisfy readers who want to go 
> > looking for more detail.
>
> What is this assertion based on?  I understand that doing so will
> satisfy you, but how do you know it will satisfy others?

I tried to explain this in an earlier post, where I wrote:

> Online release notes are usually structured so that 
> if one is reading the notes for X.Y, it's very easy to get from 
> there to the notes for X.(Y-1) -- you just scroll farther down 
> in 
> the web page, or you edit the URL in some obvious way, or 
> something like that.  Thus, people who saw Stefan's announcement 
> would have the following assumption in the back of their minds: 
> "If I can get to the release notes for 28.2, it'll be an equally 
> easy hop from there to the release notes for 28.1".  Therefore, 
> including a link to the 28.2 release notes in the 28.2 
> announcement email would help those who are upgrading from >= 
> 27.x 
> too, as well as those upgrading from 28.1.

What I said there applies (for example) to the NEWS file link you 
give above.

Once someone has landed on the Git-served NEWS web page, they can 
easily find their way to earlier release notes if the wish to.  In 
this case they would do it by searching farther down in the same 
page.  In other cases, such as if they had landed on 
https://git.savannah.gnu.org/cgit/emacs.git/tree/etc/NEWS.28, they 
might might do it via trivial URL editing.

These are common strategies that people who install software like 
Emacs generally know how to use.  I would expect that you yourself 
have used such strategies before, though I don't know for sure.

Best regards,
-Karl