Deprecate vs. discourage

Deprecate vs. discourage

[Ludovic Courtès]

Hello!

I think things like ‘uniform-vector-read’ should be discouraged rather
than deprecated, since it matches the definition in ‘discouraged.h’:

   A discouraged feature is one that shouldn't be used in new code
   since we have a better alternative now.  However, there is nothing
   wrong with using the old feature, so it is OK to continue to use
   it.

However, discouraged features currently don’t produce any sort of
warning.  I would suggest using the same technique as
‘build-aux/link-warning.h’ to issue a link-time warning.

What do you think?

Thanks,
Ludo’.

Re: Deprecate vs. discourage

[Andy Wingo]

Hej,

On Tue 26 Jan 2010 23:15, ludo@gnu.org (Ludovic Courtès) writes:

> I think things like ‘uniform-vector-read’ should be discouraged rather
> than deprecated, since it matches the definition in ‘discouraged.h’:
>
>    A discouraged feature is one that shouldn't be used in new code
>    since we have a better alternative now.  However, there is nothing
>    wrong with using the old feature, so it is OK to continue to use
>    it.
>
> However, discouraged features currently don’t produce any sort of
> warning.  I would suggest using the same technique as
> ‘build-aux/link-warning.h’ to issue a link-time warning.
>
> What do you think?

Sounds good to me :)

Andy
-- 
http://wingolog.org/

Re: Deprecate vs. discourage

[Greg Troxel]

[-- Attachment #1: Type: text/plain, Size: 1447 bytes --]


ludo@gnu.org (Ludovic Courtès) writes:

> I think things like ‘uniform-vector-read’ should be discouraged rather
> than deprecated, since it matches the definition in ‘discouraged.h’:
>
>    A discouraged feature is one that shouldn't be used in new code
>    since we have a better alternative now.  However, there is nothing
>    wrong with using the old feature, so it is OK to continue to use
>    it.
>
> However, discouraged features currently don’t produce any sort of
> warning.  I would suggest using the same technique as
> ‘build-aux/link-warning.h’ to issue a link-time warning.
>
> What do you think?

Given the history of guile, I suspect that in some number of years a
feature that has been discouraged will get moved to deprecated, and then
removed.  So the question is really what kind of commitment there is to
API/ABI stability, and I don't think there is much.

The key question is whether we mean:

  This feature exists and is the currently-known best way.

  This feature exists and we have no plan to withdraw it, but there's a
  better way.  [and implicitly, the odds of us later deciding to remove
  it are significantly higher than the previous category]

  This feature still exists, and there is a better way.  We're going to
  remove this feature in a future release, so you had really better fix
  your code not to use it.


I think discouraged is the second one.

[-- Attachment #2: Type: application/pgp-signature, Size: 194 bytes --]

Re: Deprecate vs. discourage

[Grant Rettke]

On Tue, Jan 26, 2010 at 4:15 PM, Ludovic Courtès <ludo@gnu.org> wrote:
> What do you think?

You might move said functions to a "deprecated" module.

It is minimal hassle to the user (admittedly more so than what you
explained), self-documenting, and ultimately makes it easier for
everyone because you could set a policy that deprecated is blown away
every new major release.

Re: Deprecate vs. discourage

[Ludovic Courtès]

Hi,

Grant Rettke <grettke@acm.org> writes:

> On Tue, Jan 26, 2010 at 4:15 PM, Ludovic Courtès <ludo@gnu.org> wrote:
>> What do you think?
>
> You might move said functions to a "deprecated" module.

That’s what had been done for these functions but libguile also supports
‘discouraged’ features.

Thanks,
Ludo’.

Re: Deprecate vs. discourage

[Neil Jerram]

ludo@gnu.org (Ludovic Courtès) writes:

> That’s what had been done for these functions but libguile also supports
> ‘discouraged’ features.

I never really saw the case for two levels of deprecation
(i.e. `discouraged' and `deprecated').  I thought `deprecated' on its
own was enough.

When deprecation was first invented, the notional plan was that a
deprecated thing would be removed immediately before the _second_ major
release following when it became deprecated.

    Neil

Re: Deprecate vs. discourage

[Neil Jerram]

Greg Troxel <gdt@ir.bbn.com> writes:

> Given the history of guile, I suspect that in some number of years a
> feature that has been discouraged will get moved to deprecated, and then
> removed.  So the question is really what kind of commitment there is to
> API/ABI stability, and I don't think there is much.

API/ABI stability is important, but it is also important that the
codebase can evolve.  So there must be a balance between API/ABI
stability and having to keep cruft in the codebase.

> The key question is whether we mean:
>
>   This feature exists and is the currently-known best way.

Huh?  Why would that be deprecated or discouraged?

>   This feature exists and we have no plan to withdraw it, but there's a
>   better way.  [and implicitly, the odds of us later deciding to remove
>   it are significantly higher than the previous category]
>
>   This feature still exists, and there is a better way.  We're going to
>   remove this feature in a future release, so you had really better fix
>   your code not to use it.
>
>
> I think discouraged is the second one.

I agree, but I don't think the distinction between the second and third
is helpful.  Hence I favour dropping discouraged and only having
deprecated.

Regards,
        Neil

Re: Deprecate vs. discourage

[Andy Wingo]

Hi,

On Thu 28 Jan 2010 22:28, Neil Jerram <neil@ossau.uklinux.net> writes:

> I favour dropping discouraged and only having deprecated.

I'm OK with this as well, FWIW.

Andy
-- 
http://wingolog.org/

Re: Deprecate vs. discourage

[Ludovic Courtès]

Hi Neil,

Neil Jerram <neil@ossau.uklinux.net> writes:

> ludo@gnu.org (Ludovic Courtès) writes:
>
>> That’s what had been done for these functions but libguile also supports
>> ‘discouraged’ features.
>
> I never really saw the case for two levels of deprecation
> (i.e. `discouraged' and `deprecated').  I thought `deprecated' on its
> own was enough.

I think I get your point.  OTOH, I felt that /deprecating/
‘uniform-vector-{read-write}’ might be a bit strong, as it will annoy
people who’ve been using them even though these functions are harmless.

What do you think?

Thanks,
Ludo’.

Re: Deprecate vs. discourage

[Neil Jerram]

ludo@gnu.org (Ludovic Courtès) writes:

> Hi Neil,
>
> Neil Jerram <neil@ossau.uklinux.net> writes:
>
>> ludo@gnu.org (Ludovic Courtès) writes:
>>
>>> That’s what had been done for these functions but libguile also supports
>>> ‘discouraged’ features.
>>
>> I never really saw the case for two levels of deprecation
>> (i.e. `discouraged' and `deprecated').  I thought `deprecated' on its
>> own was enough.
>
> I think I get your point.  OTOH, I felt that /deprecating/
> ‘uniform-vector-{read-write}’ might be a bit strong, as it will annoy
> people who’ve been using them even though these functions are harmless.
>
> What do you think?

If we had a perfect manual, the recommended way to do something would be
documented there, and people writing new code would use that and so
naturally use what we currently believe to be the best thing.

If something like uniform-vector-xxx stops being the recommended
approach, but remains trivial for us to support in the codebase, I think
it is enough `discouragement' just to remove it from the manual.  That
will make it less likely to be used in new code.

I think we should use the formal deprecation mechanism for something
when it becomes a burden (of any kind) for us to continue support that
thing in the codebase, or when we have a good reason to believe that it
will become a burden soon.

Does that make sense?

> Thanks,
> Ludo’.

     Neil

Re: Deprecate vs. discourage

[Ludovic Courtès]

Hi Neil,

Neil Jerram <neil@ossau.uklinux.net> writes:

> If something like uniform-vector-xxx stops being the recommended
> approach, but remains trivial for us to support in the codebase, I think
> it is enough `discouragement' just to remove it from the manual.  That
> will make it less likely to be used in new code.

Good point.

OTOH, it may not be clear to a newcomer why some functions are available
(and not deprecated) yet undocumented.

Perhaps I should just stop worrying about these two functions.  ;-)

> I think we should use the formal deprecation mechanism for something
> when it becomes a burden (of any kind) for us to continue support that
> thing in the codebase, or when we have a good reason to believe that it
> will become a burden soon.
>
> Does that make sense?

Yes, it does.

Thanks,
Ludo’.