module std.stream is deprecated - Will be removed by phobos version 2.070

[Jonathan M Davis via Digitalmars-d]

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