On the stability of Xref

On the stability of Xref

[Philip Kaludercic]

Hi,

I wanted to ask what the consensus is on the stability of the Xref
interface. xref.el starts with the unsettling warning

        ;; NOTE: The xref API is still experimental and can change in major,
        ;; backward-incompatible ways.  Everyone is encouraged to try it, and
        ;; report to us any problems or use cases we hadn't anticipated, by
        ;; sending an email to emacs-devel, or `M-x report-emacs-bug'.

that scares some people away from using the mode (see for example [0]).

git blame tells me that that this note was added more than 5 years ago,
and I'm not sure how much has changed in the interface since then.

At the same time, several external packages have implemented the Xref
interface, including the aforementioned dumb-jump, that is among the
most used packages on MELPA[1]. Eglot and lsp-mode both implement the
interface as is.

The question I am getting at is whether or not it is time to remove the
warning and accept the Xref interface as it is, or to make use of the
warning and update what should be updated? I personally am a big fan of
the functionality it provides generically, and prefer it over having
every mode do it's own thing, as I assume many others do too. Not having
to worry about it changing would be appreciated. 

[0] https://github.com/jacktasia/dumb-jump/issues/365#issuecomment-824357478
[1] https://melpa.org/#/dumb-jump

-- 
	Philip K.

Re: On the stability of Xref

[Dmitry Gutov]

Hi Philip,

On 22.04.2021 12:57, Philip Kaludercic wrote:

> I wanted to ask what the consensus is on the stability of the Xref
> interface. xref.el starts with the unsettling warning
> 
>          ;; NOTE: The xref API is still experimental and can change in major,
>          ;; backward-incompatible ways.  Everyone is encouraged to try it, and
>          ;; report to us any problems or use cases we hadn't anticipated, by
>          ;; sending an email to emacs-devel, or `M-x report-emacs-bug'.
> 
> that scares some people away from using the mode (see for example [0]).

Looking at the discussion, that sounded more like a justification than 
the real reason, but...

> git blame tells me that that this note was added more than 5 years ago,
> and I'm not sure how much has changed in the interface since then.

...it's high time to remove it anyway. And I have now done so.

> At the same time, several external packages have implemented the Xref
> interface, including the aforementioned dumb-jump, that is among the
> most used packages on MELPA[1]. Eglot and lsp-mode both implement the
> interface as is.

Since a number of highly visible packages rely on it, the changes need 
to be done more carefully already, and if I we ever get around to doing 
a major redesign/rewrite, it would probably be better incubated as an 
external package. In GNU ELPA, at least.

Thanks for the reminder,
Dmitry.