Deprecations and removals process

[Witold Baryluk]

Hi,

I just did unburrow my very old project from 2006. It was 
actually written initially in 2005 in D1, but in 2006, I update 
it to D2 (just simple changes like `char[]` -> `string`, and 
`.dup` -> `.idup` in one or two) and it worked just fine.

It is just 380 lines of easy code.

So now is 2021, I wanted to use it again. And it doesn't compile, 
requiring some fixes due to use of some old phobos stuff, and one 
minor language change.

I took it out, and after minor corrections (like `std.ctypes` -> 
`core.stdc.ctypes`), and `int` -> `size_t` (because I use 64-bit 
machine now, and should have used `size_t` from the start), 
`derr` -> `stderr`, and `writeLine` -> `writeln`, and convert 
`else {;}` which is deprecated (but makes an compile Error), to 
`else {}`.

Almost done...

I stumbled over our old friend `BufferedFile` and `OutputStream` 
from `std.stream`. It was easy to convert, but I wanted to make 
sure the semantic of the replacement is same as the old one, and 
what is the recommended replacement.

I was not able to find any mention of deprecation or removal of 
`std.stderr` in ANY DMD / Phobos release notes / changelogs.

I think this is tragic.

Don't get me wrong, deprecating stuff and removing them after 
grace period is fine, if we find better and more long term 
solutions. But they must be communicated VERY well.

I found the `undeaD`, which I never needed to use, (and because 
this program is small, I can just fix the program), and it does 
carry `std.stream`, and in one of the first commits ( 
https://github.com/dlang/undeaD/commit/d9bf1f2f3c00ae3139e9f5dcb883f32b2708d3c7#diff-6074870e72711b78f702f61a4143523ca5773e8a8fe6e6114e4f37d12640d118 ) it says, in September 2015:

```
Add std.stream and friends to undead.

Their documentation was removed from the site as of 2.068, and 
they will
be deprecated in 2.069. ....
```


However, changelogs for 2.068, 2.069 and all the one after it, 
doesn't mention anything of this sort.


I did found old docs, that do mention it is deprecated, but 
doesn't suggest replacements, why it is deprecated, and non of 
that is mentioned in changelogs.


https://docarchives.dlang.io/v2.066.0/phobos/std_stream.html    - 
Warning about intent to deprecate / find replace.

https://docarchives.dlang.io/v2.067.0/phobos/std_stream.html    - 
ditto

https://docarchives.dlang.io/v2.068.0/phobos/std_stream.html    - 
ditto

https://docarchives.dlang.io/v2.069.0/phobos/std_stream.html    - 
ditto

https://docarchives.dlang.io/v2.070.0/phobos/std_stream.html    - 
Deprecation notice, and forward notice of removal in October 2016

https://docarchives.dlang.io/v2.071.0/phobos/std_stream.html    - 
ditto

https://docarchives.dlang.io/v2.072.0/phobos/std_stream.html    - 
gone (at least in docs, not sure if it is actually gone)


However, none of this is reflected in Changelogs / Release notes.


Is there a formal process for deprecation for D and Phobos, and 
procedures that such changes undergo, to make it clear and 
discoverable?

I still can not find discussions, bugs, about the deprecation or 
removal, that would allow me to understand what happened, when 
exactly, and how I should proceed.

The example was for `std.stream`, but this applies to many other 
modules in Phobos.