On Saturday, 12 September 2015 at 14:24:21 UTC, Jacob Carlborg
wrote:
The problem with adding notifications in the documentation is
that if a user already has implemented code that uses the
particular model and have no need to change the code. Or the
user already is familiar with the module there's no reason to
read the documentation to see the notification or to notice the
documentation is gone.
It only (hopefully) prevents new users to use the module.
Would it be better to add the deprecation immediately and let
be deprecated for a longer period? Or use something like
'pragam(msg, "WARNING: deprecated ...")' if someone is using
the "-de" flag.
std.stream got a note in its documentation (something like 3
years ago) rather than being deprecated, because we didn't have a
replacement yet. We just knew that we definitely wanted to
replace it. But we have yet to actually come up with a
replacement, and when it was brought up at dconf that the note
had been on std.stream for years and yet the module was still
there, Andrei said that we should just kill it and that maybe
this was a sign that streams weren't all that important. So,
we're now actually deprecating it even though we don't have a
replacement yet.
It used to be that marking something as deprecated immediately
made that code fail to compile, which is why we used to mark
stuff as "scheduled for deprecation" in its documentation for a
while before actually deprecating it, but deprecated was fixed a
while ago so that it doesn't result in a compilation error by
default (hence the -de flag that you mentioned), and when that
change was made, we stopped marking stuff as "scheduled for
deprecation."
Normally, what we've been doing for a while now is to just
immediately deprecate a symbol (or module) and then wait about a
year before removing it from the docs, and then wait about
another year before removing it from the code. So, the result is
that existing code has about two years to be changed before it'll
stop compiling due to the symbol going away. It's just that
anyone compiling it will be bugged by deprecation messages unless
they use a flag to shut them off (which they shouldn't, because
then they'll miss all deprecation messages, but folks are free to
shoot themselves in the foot if they really want to). So, at this
point, there really isn't much point in general in saying
anything in the documentation before deprecating a symbol, and we
haven't been doing that.
The one exception that's come up is that deprecating a symbol and
introducing its replacement in the same release causes problems
for folks who need their code to build with both the current
release and master (as is the case with Vladimir). So, in a few
cases, we've marked a symbol as scheduled for deprecation when we
add its replacement and then have deprecated it in the next
release and continued the deprecation cycle as normal. But most
of the time, we've just gone straight to deprecated, and we
aren't doing a lot of deprecating these days, so it's nowhere
near the issue it was when we were doing mass renamings and
whatnot several years ago.
- Jonathan M Davis
