DIP 1013: The Deprecation Process -- Community Review Round 1

[Jonathan M Davis]

On Thursday, April 05, 2018 14:42:56 Mike Franklin via Digitalmars-d wrote:
> On Monday, 2 April 2018 at 07:05:45 UTC, Mike Parker wrote:
> > DIP 1013 is titled "The Deprecation Process".
> >
> > https://github.com/dlang/DIPs/blob/d8f6bfa1810c9774bd7d3b3dc6a7a6776ed5e
> > 17e/DIPs/DIP1013.md
> I think there should be some clarification on the stages of
> deprecation.  For example, something like this:
>
> Stage 1: T0 - Start of deprecation
>    1. The deprecated feature is added to the Deprecated Features
> page to notify the public that a decision has been made to
> deprecate the feature.
>    2. Pull requests are submitted to update relevant sections of
> the documentation notifying readers that the feature has been
> deprecated.
>    3. Pull requests are submitted to remove all usages of the
> deprecated feature from DLang repositories.
>    4. Pull requests are submitted to cause the compiler to emit
> deprecation messages for any usage of the deprecated feature, and
> to update the Deprecated Features page with the release version
> of this change.  A changelog entry is also required at this time.
>
> Stage 2: T0 + 5 non-patch releases
>    1. Pull requests are submitted to cause the compiler to emit
> error messages for any usage of the deprecated feature, and to
> update the Deprecated Features page with the release version of
> this change.  A changelog entry is also required at this time.
>
> Stage3: T0 + 10 non-patch releases
>    1. Pull requests are submitted to remove all knowledge of the
> deprecated feature from both the documentation and the
> implementation.  The Deprecated Features page is updated with the
> release version of this change.  A changelog entry is also
> required at this time.

As far as the library goes, this is not how it currently works, and I
_really_ don't want it to start working that way now. Currently, we have one
year of a symbol being deprecated and documented, and one year of a symbol
being deprecated and undocumented. The DIP follows that except that it uses
releases instead of years with the idea that we'll get approximately 5 major
releases in a year (with 1 every two months, the number should be more like
12, but since we're going to slip occasionally, saying 10 instead 12 makes
it so that we'll hit approximately the right now, and it favors removing
slightly faster over being stuck with a symbol slightly longer due to some
releases being delayed).

I see no reason to add a changelog entry when the symbol becomes
undocumented, and I see no reason to start making anything errors. That's
not how deprecations work. Unless you compile with -de, using a deprecated
symbol only prints a message - it's not even a warning. So, it has zero
effect on compilation except that any function which uses a deprecated
symbol without being marked as deprecated itself will result in deprecation
messages being printed. No code fails to compile, and -w doesn't change
anything. Years ago, we specifically made it so that deprecated didn't
generate errors, because having it generate errors made it useless. It
immeditately broke code any time you deprecated something and wasn't much
better than simply removing the symbol. The current behavior of -deprecated
is worlds better, and both the current deprecation policies and those
outlined in the DIP (which aside from the change from years to releases is
more or less the same as what happens now for Phobos) work quite well with
how -deprecated works.

Adding a changelog entry when the symbol is deprecated and when it is
removed seem plenty.

Overall, this DIP is simply formalizing what we do now with deprecations for
Phobos, and I'd very much like it to stay that way. Clarifying the
deprecation process is fine with me, but what we've been doing (as far as
the library goes anyway) has largely been working, and I don't want it to be
changed without a really good reason (especially since I'm the main person
mananging it).

As for deprecations in the language itself, that's never been particularly
consistent or formalized. This seems to do that fairly well by essentially
saying that language features should be deprecated for the same length as
symbols in the library. It's just that the language feature doesn't get
undocumented halfway through the deprecation cycle, and the process of what
you have to do beyond actually deprecating the feature is a bit different,
because there are other things that have to be considered (e.g. updating the
spec).

> > In order to facilitate on schedule deprecations, a comment of
> > the format @@@DEPRECATED_[version]@@@ should be added to the
> > top of the code to be removed/disabled.
>
> Is `[version]` the version in which the deprecation took place,
> or the future version in which the next stage is to take place.
> For example, if I'm deprecating a feature in 2.080, should
> `[version]` be 2.080, or 2.085 (the version in which the features
> is changed to an error)?

As I said before, it's never changed to an error. The DIP quite specifically
never does that, and really I don't think that it should. However, the point
about which release to mention in the message not being clear is a good one.
What I've typically been doing has been to document the release that the
symbol is going to be removed from the documentation, and then when I
undocument the symbol, I add a non-ddoc comemnt with a note about when it's
actually scheduled to be removed. We haven't typically been putting the date
of removal (either from the documentation or the library) in the deprecation
message itself.

However, putting the date that the documentation is going to be removed in
the documentation has proven to be confusing. One result is that often,
folks have mistakenly thought that the deprecation cycle was one year
instead of two. As such, I think that going forward, we should be the
release for removal in the documentation (and the deprecation message, since
the DIP formalizes that it goes there too). It should be fairly easy to
figure out when a symbol should be undocumented based on the release that
it's marked for removal. You just subtract five. And if in a particular
case, we need to adjust the removal schedule and thus undocument the symbol
at a release other than removal - 5, then we can just add a note in a
non-ddoc comment.

- Jonathan M Davis