How to warn about obsolete file in ELPA package

How to warn about obsolete file in ELPA package

[Basil L. Contovounesios]

I'm preparing to update the dash package on GNU ELPA and MELPA.
One of the planned changes for this upcoming 2.18.0 release is
the consolidation of its two constituent files dash.el and
dash-functional.el.

The latter was split off as a separate file in the past due its reliance
on lexical-binding.  Since then, dash.el has also come to depend on
Emacs 24, so we have agreed to move the definitions in
dash-functional.el to dash.el and eventually delete dash-functional.el.

The problem is that GNU ELPA has historically bundled both dash.el and
dash-functional.el under the dash package, and MELPA has bundled each as
a separate package.  In either case, a transitional dash-functional.el
file/package must be kept around for a while for backward compatibility.

We would like to emit an obsoletion warning when dash-functional.el is
used, similar to the one for lisp/obsolete/* libraries.  Hopefully such
a warning will be seen as helpful and actionable rather than annoying.

What is the best way to go about this to cover the cases where
dash-functional.el is byte-compiled, installed, or loaded?

One simple way is a top-level (lwarn 'dash :warning "Foo"), but the
message printed during byte-compilation is not recognised in
*compilation* buffers as a warning, so I fear the message may go
unnoticed.

Another option is a top-level (byte-compile-warn "Foo").  This isn't
picked up as a warning either, but at least the file name is fontified
with font-lock-function-name-face, so it sticks out a bit more.

Any suggestions along these or any better lines are most welcome.

If you're interested in the relevant discussions, see the following:
https://github.com/magnars/dash.el/wiki/Obsoletion-of-dash-functional.el
https://github.com/magnars/dash.el/issues/356

TIA,

-- 
Basil

Re: How to warn about obsolete file in ELPA package

[Basil L. Contovounesios]

"Basil L. Contovounesios" <contovob@tcd.ie> writes:

> We would like to emit an obsoletion warning when dash-functional.el is
> used, similar to the one for lisp/obsolete/* libraries.  Hopefully such
> a warning will be seen as helpful and actionable rather than annoying.
>
> What is the best way to go about this to cover the cases where
> dash-functional.el is byte-compiled, installed, or loaded?
>
> One simple way is a top-level (lwarn 'dash :warning "Foo"), but the
> message printed during byte-compilation is not recognised in
> *compilation* buffers as a warning, so I fear the message may go
> unnoticed.
>
> Another option is a top-level (byte-compile-warn "Foo").  This isn't
> picked up as a warning either, but at least the file name is fontified
> with font-lock-function-name-face, so it sticks out a bit more.

Sorry, I was confused: the above is what happens when loading
dash-functional.el noninteractively, not when byte-compiling it.

What about something like the following at top-level?

(eval-and-compile
  (let ((msg "Package dash-functional is deprecated; use dash 2.18.0 instead"))
    (if (and noninteractive (fboundp 'byte-compile-warn))
        (byte-compile-warn msg)
      (message "%s" msg))))

> Any suggestions along these or any better lines are most welcome.

Note that they should work in Emacs versions 24 and above.

TIA,

-- 
Basil

Re: How to warn about obsolete file in ELPA package

[Stefan Monnier]

> We would like to emit an obsoletion warning when dash-functional.el is
> used, similar to the one for lisp/obsolete/* libraries.

I think you can get exactly this behavior by placing the file in
a directory called `obsolete`.


        Stefan

Re: How to warn about obsolete file in ELPA package

[Basil L. Contovounesios]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> We would like to emit an obsoletion warning when dash-functional.el is
>> used, similar to the one for lisp/obsolete/* libraries.
>
> I think you can get exactly this behavior by placing the file in
> a directory called `obsolete`.

I don't think this will work with MELPA which bundles dash-functional as
its own single-file package.

-- 
Basil

Re: How to warn about obsolete file in ELPA package

[Stefan Monnier]

>>> We would like to emit an obsoletion warning when dash-functional.el is
>>> used, similar to the one for lisp/obsolete/* libraries.
>> I think you can get exactly this behavior by placing the file in
>> a directory called `obsolete`.
> I don't think this will work with MELPA which bundles dash-functional as
> its own single-file package.

You'd have to make it a tarball, yes, but AFAIK MELPA supports tarballs
just fine, so I don't see it as a problem (but then again, I don't see
the benefit of having a package in MELPA when it's already in GNU ELPA,
so there are clearly things that are beyond my understanding ;-).


        Stefan

Re: How to warn about obsolete file in ELPA package

[Basil L. Contovounesios]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>>> We would like to emit an obsoletion warning when dash-functional.el is
>>>> used, similar to the one for lisp/obsolete/* libraries.
>>> I think you can get exactly this behavior by placing the file in
>>> a directory called `obsolete`.
>> I don't think this will work with MELPA which bundles dash-functional as
>> its own single-file package.
>
> You'd have to make it a tarball, yes, but AFAIK MELPA supports tarballs
> just fine

Really?  -Grumble, more work...-

> so I don't see it as a problem (but then again, I don't see
> the benefit of having a package in MELPA when it's already in GNU ELPA,
> so there are clearly things that are beyond my understanding ;-).

The problem here is that no-one cared to sync the version on GNU ELPA
with its upstream in 6 years :(.

-- 
Basil

Re: How to warn about obsolete file in ELPA package

[Philipp]

> Am 06.02.2021 um 16:03 schrieb Stefan Monnier <monnier@iro.umontreal.ca>:
> 
>> We would like to emit an obsoletion warning when dash-functional.el is
>> used, similar to the one for lisp/obsolete/* libraries.
> 
> I think you can get exactly this behavior by placing the file in
> a directory called `obsolete`.
> 

Could we add something like (cl-declaim obsolete) to make this independent of the filename?

Re: How to warn about obsolete file in ELPA package

[Stefan Monnier]

>>> We would like to emit an obsoletion warning when dash-functional.el is
>>> used, similar to the one for lisp/obsolete/* libraries.
>> I think you can get exactly this behavior by placing the file in
>> a directory called `obsolete`.
> Could we add something like (cl-declaim obsolete) to make this independent of the filename?

You can probably cook something up using `macroexp--warn-and-return`.
E.g. something like:

    (defmacro my-\, (exp) (eval exp t))
    (my-\,
     (when (fboundp 'macroexp--warn-and-return) ;; New in Emacs-24.3
       (macroexp--warn-and-return
        "dash-functions is obsolete, just require dash instead" nil)))


-- Stefan