Let's talk about deprecations

Mon Jul 3 04:30:14 PDT 2017

On Sunday, July 02, 2017 23:27:26 Seb via Digitalmars-d wrote:
> Hi all,
>
> I think we need to talk about deprecations.
> A recent example on [Phobos][#5532] uncovered an ugly truth: many
> people don't seem care about deprecation warnings.
>
> #5532 wanted to remove the symbols scheduled for deprecation -
> most noteworthy here the removal of std.c.
> FYI std.c was [deprecated  in September 2014][#2337].
> Now, almost three years later, we have Martin's great project
> tester and for the first time we can assess the impact of turning
> deprecations into errors on the D ecosystem. The problem here is
> that the Project-Tester doesn't even get to the state of testing
> external projects, because it already fails on building
> [DUB][dub] and [rdmd][rdmd].
> Without being able to see the failing, external projects on the
> Project-Tester I can only guess and with from looking at a few
> projects (e.g. [vibe.d][vibe.d]) it doesn't seem that there's fun
> ahead.
>
> Proposals
> ---------
>
> I think we should learn from the past. Here are a couple of ideas:
>
> 1) Stop making such a fuzz about having a long deprecation
> period. Most people will only care about a deprecation when their
> project doesn't compile anymore. A deprecation period of two
> releases is more than enough for users that care. As seen even
> _eight_ releases don't help! (std.c was deprecated in 2.067)
> 2) List deprecations in the changelog - users who care read it
> (and as seen there isn't any point to cater or wait for those who
> don't. I stress this point because people notoriously don't add
> their breaking changes to the changelog, which I guess has led to
> frustration & complains in the past and thus resulted in the
> currently cautious attitude against deprecations).
> 3) Ship a tool like dfmt with new releases that allows easy
> upgrades to new releases
> 4) Solve the problem automatically: let a bot that crawl _all_ D
> source code on GH and let it submits PRs for trivial deprecations
> (could be based on dfmt or other tools)
>
> Especially with (3) (and optionally (4)) deprecations should
> become a lot less painless and they might again gain the glance
> of "awesome, we are getting rid of old, ugly stuff" instead
> "please don't break anything".
>
> [#5532]: https://github.com/dlang/phobos/pull/5532
> [#2337]: https://github.com/dlang/phobos/pull/2337
> [dub]: https://github.com/dlang/dub/issues/1183
> [tools]: https://github.com/dlang/tools/issues/238
> [vibe.d]: https://github.com/rejectedsoftware/vibe.d/issues/1811

Usually, these discussions go in the opposite direction, with some folks
arguing that deprecated stuff should be left around forever, which I don't
want to see happen, which is part of why I specifically avoid ever starting
discussions about how long depreactions are. What we've been doing (one year
as deprecated and documented and and one year as deprecated but undocumented
- and then removal) has largely been working.

Remember, not everyone is rebuilding all their stuff with every dmd release.
If something is working, many folks have no reason to rebuild it for months,
so they're not going to see any deprecation messages. Heck, at one point,
_Walter_ complained, because of a project of his wouldn't compile anymore,
because symbols had been removed from Phobos, and those symbols had gone
through the full two-year deprecation process, and he'd never seen the
deprecation messages. He hadn't touched that project in over two years. In
that sort of situation, it's reasonable to grab a year-old compiler, fix all
the deprecations, and then get it working with the current compiler, but if
we're deprecating and removing symbols within only a few months, you risk
having to try a whole series of compiler releases to track down and fix all
of the changes. And Walter was annoyed enough at the idea of having to use
_one_ intermediate compiler to get the missed deprecation messages. _I_ sure
wouldn't want to have to try a series of intermediate compilers to be able
to update my code.

Those who build their stuff frequently and care will see the deprecation
messages and update their stuff relatively quickly. Those who don't build
their stuff often are _far_ more likely to see the deprecation messages when
the deprecation cycle is longer and thus have fewer problems. And those who
don't care won't change their stuff until they're forced to, so why should
we care what they do?

It makes sense to list it in the changelog when something is deprecated
(that happens at least some of the time, but I don't know how frequently;
personally, I stopped bothering with the changelog for anything ages ago,
because it was too much of a pain to deal with, and we keep changing how it
even works to add anything to it), but someone who isn't going to pay
attention to a deprecation message, isn't going to pay attention to the
changelog, and in general, the deprecation message is going to reach _far_
more people than the changelog, because as soon as you compile, you see the
deprecation message, but no one actually _needs_ to look at the changelog
for anything. It's just a useful resource for those who bother reading it.
So, having stuff in the changelog is good, but it's just a way to help
inform people, not a way that you can guarantee anything about the affected
folks finding out - let alone caring enough to update their code.
Ultimately, the way that folks find out about needing to change their code
is compiling it and seeing the deprecation messages - or getting compilation
errors if they wait too long, but that's a _lot_ more of a pain to deal with
than the deprecation messages, so we really don't want to rush the removal.

The reality of the matter is that we will _always_ have to deal with users
who failed to compile their code frequently enough to catch the deprecation
messages and that we'll always have to deal with users who just won't bother
updating their code until it won't compile anymore, because the symbol was
removed. But by having longer deprecation cycles, we give folks ample time
to find out that their project needs to be updated so that we're not
screwing over users who aren't constantly upgrading. Anything we want to do
with the changelog to inform people or with tools to help people make the
transition is fine, but I see no reason to change what we've been doing with
the length of the deprecation process. Overall, it's been working just fine,
and there really haven't been many complaints about it. And those who have
complained have generally complained because a symbol was deprecated at all,
not because the length of the deprecation process was too long.

No matter what you do, you're not going to solve the problem of _someone_
not updating their code to deal with a deprecation unless you simply don't
deprecate anything - which just causes a different set of problems. And
remember that folks who are constantly dealing with the most up-to-date dmd
are unlikely to be the norm, even if most of the folks who post anything
here generally do use a recent compiler version.

- Jonathan M Davis