Re: New Eglot release

[Eli Zaretskii]

> From: João Távora <joaotavora@gmail.com>
> Date: Fri, 10 Mar 2023 12:50:27 +0000
> Cc: jp@neverwas.me, philipk@posteo.net, emacs-devel@gnu.org
> 
> > > Eli, is this patch good to push?  It adds a new etc/EGLOT-NEWS and makes
> > > a tiny mention to it in etc/NEWS.
> >
> > EGLOT-NEWS mentions many bugfixes, something that we don't do in
> > NEWS.  The style is also very different:
> 
> Yes, it's quite different and this is in big part why I opted for
> a separate file, so hopefully these idiosyncrasies could be
> at least tolerated.

You wanted my opinion; I don't like the style.

> > > +(github#29)
> > > +
> > > +** Handle experimental/unknown server methods gracefully.
> >
> > This doesn't say enough about the change, so why mention it?  And why
> > the GitHub reference there?
> 
> For readers to get access to the original context.

That's IMNSHO is a disservice for the readers.  We should not force
them to go places and read there about the changes, we should provide
enough information for them to understand what has been changed
without going anywhere.  In the few cases where a change is too
complex to describe, we direct to the manual (which is party of the
distribution, and thus at the reader's fingertips).

> > > +** Hierarchical symbols are supported in Imenu.
> > > +Thanks to Ingo Lohmar for the original implementation (github#303).
> >
> > We don't mention individual contributors in NEWS.  They are mentioned
> > in AUTHORS instead (and if you want, also in doc/emacs/ack.texi).
> 
> Yeah, again pre-merge.  At the time I didn't have an AUTHORS file and
> I wanted to thank certain contributors specially for certain
> contributions.  Shall I remove these mentions? (Sorry Ingo :-) )

AUTHORS are generated from ChangeLog files, so they will catch all the
contributions in Git.  Since AFAIU the Eglot history was preserved in
Emacs, those contributions will be caught as well, I think?

> > > +(github#196)
> > > +
> > > +** Completion sorting fixed.
> >
> > This (and other similar entries) are not very useful, IMNSHO.
> >
> > Moreover, I don't think I see why mentioning past versions of Eglot
> > that were never parts of Emacs would be useful to someone.
> > It might be okay to have that on ELPA,
> 
> Eglot is a :core GNU ELPA package, meaning its source files and its
> documentation lives in the Emacs.git repo.

Does that mean the ELPA tarball cannot include files that are not in
the Emacs Git repository?

> > but I don't see why we'd want this in Emacs core.
> 
> I think it's quite nice to have a historical record of Eglot's
> evolution, to see how far it has come, how certain decisions were
> taken and adjusted over the years.

NEWS is not about evolution, it's about changes in specific versions.
Since Emacs will not come with past versions of Eglot, mentioning
those doesn't seem useful.

> > > +mode: outline
> > > +mode: bug-reference-mode
> >
> > Why not emacs-news-mode?
> 
> Because, for some reason I didn't investigate, it erases my
> bug-reference-bug-regexp and the links stop working.

You mean emacs-news-mode and bug-reference-mode are incompatible?
Then perhaps we should fix emacs-news-mode?

> > > +Please send Eglot bug reports to 'bug-gnu-emacs@gnu.org', and Cc (or
> > > +X-Debbugs-CC) the maintainer 'joaotavora@gmail.com' as well.  Please
> > > +read the chapter titled "Troubleshooting" in the Eglot manual,
> > > +available https://joaotavora.github.io/eglot/#Troubleshooting-Eglot
> >
> > The Eglot manual is now part of Emacs, not on GitHub.
> 
> When Emacs 29 is releasd, probably the Eglot manual will be in GNU
> sites _for that release, but not for all the other intermediate releases
> of the :core ELPA package.
> 
> AFAIK, the only place where an up-to-date version is published
> for users to read is that link (I'm happy to be shown otherwise, so
> I don't have to do this periodic chore anymore).

It makes no sense to me to point to the outdated manual on GitHub.
I'm not aware of any other bundled package which does something like
that.