On obsoleting defcustoms

On obsoleting defcustoms

[Stefan Kangas]

I see two issues with how defcustoms are currently being obsoleted.
See `M-x customize-group RET dired RET', for example.

1. Why is Emacs offering to customize something that has no effect?

See "Dired Free Space Args", whose documentation says:

   This variable is obsolete since 27.1;
   ignored, as Emacs uses ‘file-system-info’ instead

Would it make sense to change ignored options such as this into defvars
instead?  (We could keep variables like "Dired Load Hook" as a
defcustom, since it still has an effect.)

2. Finding out that an option is obsolete

The obsolete options use a different face.  However, it's not obvious
that this is the meaning of that face.

One either has to run `what-cursor-position' to see that the face is
named `custom-variable-obsolete', or expand first the option itself, and
then its documentation, and then after having seen a couple of examples
induce that the face means "obsolete".

Could we add some other marker besides just the color to show that these
options have been declared obsolete?  For example by adding the text
"(obsolete)" in a prominent location.

Best regards,
Stefan Kangas

Re: On obsoleting defcustoms

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 18 Sep 2020 06:01:14 -0700
> 
> Would it make sense to change ignored options such as this into defvars
> instead?

What problem would that solve?  Not all obsolete defcustoms have no
effect, do they?

> 2. Finding out that an option is obsolete
> 
> The obsolete options use a different face.  However, it's not obvious
> that this is the meaning of that face.

IMO, we shouldn't show obsolete options at all in a Custom buffer, for
the same reason why we remove them from the manuals.

Re: On obsoleting defcustoms

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> IMO, we shouldn't show obsolete options at all in a Custom buffer, for
> the same reason why we remove them from the manuals.

Yes, that is an even better solution.  Thank you for pointing it out.

RE: On obsoleting defcustoms

[Drew Adams]

> > Would it make sense to change ignored options such as this into
> > defvars instead?
> 
> What problem would that solve?  Not all obsolete defcustoms have no
> effect, do they?
> 
> > 2. Finding out that an option is obsolete
> >
> > The obsolete options use a different face.  However, it's not obvious
> > that this is the meaning of that face.
> 
> IMO, we shouldn't show obsolete options at all in a Custom buffer, for
> the same reason why we remove them from the manuals.

Just because something is declared obsolete, that doesn't
(normally) mean that it's not supported or that it doesn't
still work.

Dunno whether that's true (always? sometimes? never?) for Emacs.

But if it is, then why would it make any more sense to remove
customization of an obsolete option that it would to remove
advising an obsolete function or setting an obsolete defvar?

If people are concerned about someone continuing to use
something that's obsolete, why not just have Customize give
a warning/message saying that the option is obsolete, and 
that the effect of changing its value is undefined?

That's assuming that Emacs takes the (unusual, IME) point of
view that, once declared obsolete, something should no longer
be usable.  And in that case, the right way to handle it would
be to raise an error when it's used.  We don't, thankfully, do
that.

RE: On obsoleting defcustoms

[Stefan Kangas]

[[ For context, I have just filed this bug:
   bug#44598: [PATCH] Do not show obsolete options in customize ]]

Drew Adams <drew.adams@oracle.com> writes:

> If people are concerned about someone continuing to use
> something that's obsolete, why not just have Customize give
> a warning/message saying that the option is obsolete

That's what we do now.  See `M-x customize-group RET browse-url RET' in
Emacs 27 for a bad case of what that might look like.

> That's assuming that Emacs takes the (unusual, IME) point of
> view that, once declared obsolete, something should no longer
> be usable.

It's still usable with the patch, just not advertised.

RE: On obsoleting defcustoms

[Drew Adams]

> > If people are concerned about someone continuing to use
> > something that's obsolete, why not just have Customize give
> > a warning/message saying that the option is obsolete
> 
> That's what we do now.  See `M-x customize-group RET browse-url RET'

I don't see any such warnings/messages there, until you
open the full doc string of an option.  If every option
in the group is obsolete, and so is the group itself
(which should presumably follow), then one might expect
a notification at the top (i.e. customize-group) level.

> in Emacs 27 for a bad case of what that might look like.

What's bad about it?

If all of those options still "work", a user should be
able to make use of Customize to change their values.

And if they don't work then there should be no supporting
code, and they'd be unrecognized - raise an error if
referenced in any way.  Typically, deprecated/obsolete !=
unsupported.  Does Emacs take the point of view that all
of this is unsupported?  If so, remove its code, so using
raises an error.

> > That's assuming that Emacs takes the (unusual, IME) point of
> > view that, once declared obsolete, something should no longer
> > be usable.
> 
> It's still usable with the patch, just not advertised.

Not advertising is fine.  Telling users, including in the
Customize UI, that something is obsolete is also fine.
What's not fine, IMO, is to remove it from Customize.  If
something is removed from Customize then it's not the case
that it's still usable with Customize (or Customize is
still usable for it).

RE: On obsoleting defcustoms

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

>> That's what we do now.  See `M-x customize-group RET browse-url RET'
>
> I don't see any such warnings/messages there, until you
> open the full doc string of an option.

We have the face `custom-variable-obsolete', but indeed the warning is
unfortunately only made explicit on the help screen.

>> in Emacs 27 for a bad case of what that might look like.
>
> What's bad about it?

There are more obsolete options than relevant ones.  (Including, e.g.,
the options for the now wildly irrelevant Mosaic browser.)

> If all of those options still "work", a user should be
> able to make use of Customize to change their values.
>
> And if they don't work then there should be no supporting
> code, and they'd be unrecognized - raise an error if
> referenced in any way.  Typically, deprecated/obsolete !=
> unsupported.  Does Emacs take the point of view that all
> of this is unsupported?  If so, remove its code, so using
> raises an error.

The problem is that, AFAICT, it is not really feasible to have a
one-size-fits-all for how we go about deprecating options.  In some
cases it makes sense for them to continue to have effect during the
obsoletion period, but in other cases it does not.

I for one was bitten by this trying to customize an option that turned
out to simply no longer have any effect.  Should it have just been
removed in this case?  Well, it would of course have helped me.  But
third-party code that tried to use it would get the signal "Symbol's
value as variable is void" at run-time, instead of the much gentler
byte-compiler warning that it is obsolete.

Not showing it in `M-x customize-group' seems like a good compromise.

> What's not fine, IMO, is to remove it from Customize.  If
> something is removed from Customize then it's not the case
> that it's still usable with Customize (or Customize is
> still usable for it).

The current proposal as discussed in the bug will keep both
`customize-option' and `customize-saved'.  So you can still customize
them using customize.

RE: On obsoleting defcustoms

[Drew Adams]

> > And if they don't work then there should be no supporting
> > code, and they'd be unrecognized - raise an error if
> > referenced in any way.  Typically, deprecated/obsolete !=
> > unsupported.  Does Emacs take the point of view that all
> > of this is unsupported?  If so, remove its code, so using
> > raises an error.
> 
> The problem is that, AFAICT, it is not really feasible to have a
> one-size-fits-all for how we go about deprecating options.  In some
> cases it makes sense for them to continue to have effect during the
> obsoletion period, but in other cases it does not.
> 
> I for one was bitten by this trying to customize an option
> that turned out to simply no longer have any effect.

But are you then applying your lesson from that one
option to all of these options?  Doesn't that
contradict your previous paragraph?

(And there are likely some non-obsolete options that in
some cases have no effect.)  But see what I wrote above:
if an option no longer works then we should raise an
error when it's referenced - it should be desupported.

Obsolete should mean still works and is still supported,
but is no longer being actively developed.  Desupport
means the code supporting it is gone and we raise an
error instead.

> Should it have just been
> removed in this case?  Well, it would of course have helped me.  But
> third-party code that tried to use it would get the signal "Symbol's
> value as variable is void" at run-time, instead of the much gentler
> byte-compiler warning that it is obsolete.

It's either one or the other, no?

If it doesn't work then users deserve the runtime error.
In that case, what good is a byte-compiler message
intended to warn you to move away from using it?

If it does work, and we just want you to move away from
it, then a warning makes sense.  What are we warning
about?  The fact that it might become desupported at
some point.  That's the point of a deprecation notice
and warnings.

> Not showing it in `M-x customize-group' seems like a
> good compromise.

If it no longer works, yes.  But in that case we
should raise an error, not issue a compiler warning.

If it does still work then I see no reason why we'd
remove it from `customize-group'.  Especially if
`customize-option' still works etc.  This makes no
sense to me.  (Just one opinion.)

> > What's not fine, IMO, is to remove it from Customize.  If
> > something is removed from Customize then it's not the case
> > that it's still usable with Customize (or Customize is
> > still usable for it).
> 
> The current proposal as discussed in the bug will keep both
> `customize-option' and `customize-saved'.  So you can still customize
> them using customize.

See above.  I don't see how that helps users.

RE: On obsoleting defcustoms

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

> Obsolete should mean still works and is still supported,
> but is no longer being actively developed.  Desupport
> means the code supporting it is gone and we raise an
> error instead.

Is "desupported" defined in Emacs development?  Searching online, I
was only able to find that word used in reference to Oracle Database.

I think we talk about "making obsolete" and "removing" a
variable/function/face, and their definitions are:

a) Obsolete means the byte-compiler warns about their use
b) Removed means it no longer exists

Note that we have many obsolete variables that are declared to be "no
longer used", that is, they have no effect.  You are free to argue
against the status quo, of course, but that is what we have.

> If it doesn't work then users deserve the runtime error.

I don't think raising a run-time error is wise just because we decided
that a variable should have no effect.  That would mean gratuitously
breaking code that might otherwise be working.  It is better to allow
for a grace period by raising an obsoletion warning.

> I don't see how that helps users.

The point IMO is that advertising features that we are planning to
remove does not help users.  On the contrary, we should recommend
moving away from obsolete features.

RE: On obsoleting defcustoms

[Drew Adams]

> > Obsolete should mean still works and is still supported,
> > but is no longer being actively developed.  Desupport
> > means the code supporting it is gone and we raise an
> > error instead.
> 
> Is "desupported" defined in Emacs development?  Searching online, I
> was only able to find that word used in reference to Oracle Database.

No idea, and I don't care what terms we use.

There's often (usually?) a distinction between these 3
levels of support (these are descriptions, not names):

1. Actively supported and developed.  If you file a
   bug or suggest an enhancement it will likely be
   looked at, at some point.

2. Not actively supported and developed, but still in
   the code, still working (but support for fixing bugs
   may not be there or may be reduced), and maybe even
   still documented to some extent.

3. Not supported at all.  Doesn't work.  Not in the code.
   Not documented (except old doc out on the wild web).

Each is a gray area, and different organizations have
different policies and draw lines in different places.

In principle, at least, #2 is transitional, or at least
users are told that the feature _might_ at some point
in the future change to status #3.  Things may continue
to work, but you're recommended to use the preferred
alternative/replacement (if any).

Since in #3 the feature is absent - doesn't work, you
generally get an error if you try somehow to use it.

The transition from #1 to #2 is sometimes called
deprecation, and in #2 the feature is sometimes called
obsolete or deprecated.  In #3, the feature no longer
exists, and it's sometimes said to be unsupported.
The transition from #2 to #3 is sometimes called
desupport.

There's no obligation to move from #2 to #3, BTW.  At
least in business, where there can be particularly
important customers, some features may be deprecated
(move to #2) with no intention or expectation that they
will ever really be moved to #3.

Users might not be told that, however, since the idea
is to get them to abandon the deprecated feature.
But some considerations can come into play that make
it impossible or undesirable to ever really remove a
feature altogether.

> I think we talk about "making obsolete" and "removing" a
> variable/function/face, and their definitions are:
> 
> a) Obsolete means the byte-compiler warns about their use
> b) Removed means it no longer exists

OK, that sounds to me like #2 and #3, respectively.

> Note that we have many obsolete variables that are declared to be "no
> longer used", that is, they have no effect.  You are free to argue
> against the status quo, of course, but that is what we have.

Maybe so.

We also have lots of stuff that's called obsolete and
that still works - thank goodness, IMO!  It may no
longer be used much by the distributed Emacs code, but
it may well still be used by Emacs users.

And even if an obsolete feature is no longer used, that
doesn't necessarily mean that it would have no effect
if someone did use it.

If something really has no effect then there's no reason
to warn about using it.  There may be, and often is, a
reason to retain code that just raises an error for
something that's unsupported (which isn't quite the same
thing as having no effect, but it's at least not having
the expected effect).

> > If it doesn't work then users deserve the runtime error.
> 
> I don't think raising a run-time error is wise just because we decided
> that a variable should have no effect.  That would mean gratuitously
> breaking code that might otherwise be working.  It is better to allow
> for a grace period by raising an obsoletion warning.

It sounds like we maybe have different understandings
of "have no effect".

A variable that has no effect isn't a variable.  It's
not even an unbound variable.  But yes, if you want to
remove a variable from having its formerly expected
effect, then unbind it so users get an unbound error.

A variable that continues to have its expected effect,
or at least some semblance of that, and that you're
warned/recommended not to continue to use, is just
obsolete - it's not yet missing/removed.

> > I don't see how that helps users.
> 
> The point IMO is that advertising features that we are planning to
> remove does not help users.  On the contrary, we should recommend
> moving away from obsolete features.

Yes, a warning is appropriate in that case.  Removing
the feature is something else.

You're keeping `customize-option' for such a variable,
but you're removing it from `customize-group'.  To me
that's not a great approach, but it's not a big deal.

And I wouldn't call keeping either of those customize
possibilities "advertising".  If you remove the
possibility of using an option as an option, i.e.,
remove its usual customization, then you've removed
more than advertising.

OK, you've only removed some, not all, possibilities
of customizing - just `customize-group', I guess.
You did that to reduce noise in the group UI.  That's
understandable.  I suggested instead keeping the
obsolete options in the group but showing warnings
there for them.  Not a big deal anyway.

These things aren't hard & fast rules.  They're
judgment calls.  And opinions can differ.

Re: On obsoleting defcustoms

[Eli Zaretskii]

> Date: Thu, 12 Nov 2020 13:37:24 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: emacs-devel@gnu.org
> 
> But if it is, then why would it make any more sense to remove
> customization of an obsolete option that it would to remove
> advising an obsolete function or setting an obsolete defvar?

I didn't say we should remove customization of those, I said we should
not show them in the "customize group" buffer.

> If people are concerned about someone continuing to use
> something that's obsolete, why not just have Customize give
> a warning/message saying that the option is obsolete, and 
> that the effect of changing its value is undefined?

We already say that, since we show the doc string.

> That's assuming that Emacs takes the (unusual, IME) point of
> view that, once declared obsolete, something should no longer
> be usable.

Not "usable", "used".

Re: On obsoleting defcustoms

[Eli Zaretskii]

> Date: Thu, 12 Nov 2020 17:59:34 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: emacs-devel@gnu.org
> 
> > Not showing it in `M-x customize-group' seems like a
> > good compromise.
> 
> If it no longer works, yes.  But in that case we
> should raise an error, not issue a compiler warning.
> 
> If it does still work then I see no reason why we'd
> remove it from `customize-group'.  Especially if
> `customize-option' still works etc.  This makes no
> sense to me.  (Just one opinion.)

Your opinion is noted.  I think otherwise, and so does Stefan; others
who chimed in didn't think the idea was wrong, either.  So let's agree
to disagree, and please let's stop arguing about this aspect of the
issue.  Our decision is that we want to remove the obsolete options
from display where that makes sense, to advertise them less.