Improving deprecation management

[Jonathan M Davis]

On Wednesday, November 13, 2013 18:19:49 Dicebot wrote:
> There is one thing that seems really inconvenient to me but I'd
> like to see community opinion before writing a DIP :) It is all
> about current semantics of "deprecated" attribute.
> 
> Right now using deprecated symbols is a warning. And if you use
> "-w" switch (like most pedantic projects do) it is an error that
> halts the compilation. It is possible to use "-d" to avoid
> breaking stuff but then it will just work silently, with no
> message at all.
> 
> In practice, I tend to always apply the following deprecation
> path:
> 
> 1) Modify the code to print message about upcoming deprecation
> (via pragma(msg))
> 2) On previously defined date mark symbol as deprecated and
> define expected removal date
> 3) Remove it completely
> 
> It is very inconvenient to do manually but necessary to make
> deprecation process smooth - initially I just want to make users
> aware that some time should be scheduled to adjust their code in
> future, without any interfering with normal compilation. Then do
> actual deprecation that will result in an error but still provide
> meaningful message about changes that need to be made. And only
> after that removal is viable.
> 
> I'd really love to be able to provide date/time parameter in some
> way to deprecate attribute and let compiler do all this routine
> for me automatically - just print message (not a warning) if
> compiled before the date, act as it does now after.

That would actually be a _big_ problem for code maintainability. The same 
compiler binary _must_ be able to compile exactly the same set of programs no 
matter when it's used. I should be able to compile exactly the same set of 
programs with a particular compiler binary ten years from now as I can today. 
Anything else will be a huge problem for real world environments that use the 
same compiler for years at a time. It's not always an option to update the 
code or the compiler, and even if it is and even if you do update the code and 
the compiler, you need to be able to reproduce old builds, and that won't work 
if deprecated symbols suddenly stop working just because the date changed.

I can understand why such a feature would be desirable from the perspective of 
the one who has to put the symbol through the various stages of the 
deprecation process, but it's ultimately a bad idea (and this is coming from 
the fellow who is generally the one to make sure that deprecated stuff goes 
through the full deprecation process in Phobos once it's been deprecated).

> So far I have not found see any way to define a good deprecation
> path with an existing toolset.
> 
> Opinions / recommendations?

We ended up with what we have, because it's simple and works, and Walter 
doesn't like the idea of having deprecated become complicated. Lots of ways to 
improve it have been discussed in the past, and it was agreed to make it to so 
that you could add a message to deprecated. Anything more complicated was 
rejeceted. The only other big change was to make it so that deprecation 
warnings were warnings rather than errors, which makes it possible to 
deprecate stuff without breaking code, whereas before, it was guranteed to 
break code. And -w does _not_ turn deprecation warnings into errors (and I 
just confirmed that with a simple test program). So, while I'm actually 
inclined to think that -w should be gotten rid of anyway (since it changes the 
behavior of code), it doesn't actually cause any problems with deprecated 
symbols.

I very much doubt that you will get Walter to agree to anything more 
complicated than what we currently have. And while more complicated 
deprecation features might be nice, I really don't think that we need them. At 
this point I'm inclined to think that the deprecation process should be as 
simple as

1. Mark symbol as deprecated with a message indicating what the programmer 
should use instead (preferrably with the documentation giving some indication 
as to when the symbol will be fully removed). e.g.

deprecated("Use bar insead.") void foo() {}

2. Remove the symbol.

Nothing else is really required. If you're being more paranoid (as we tend to 
be with the standard library), then the process can be made slightly longer to 
give people more time to change their code without leaving the deprecated 
symbol in the documentation for people to continue to try and write new code 
with.

1. Mark symbol as deprecated.
2. Remove the symbol's documentation.
3. Remove the symbol.

Regardless, I don't think that we really need to add any more features to 
deprecated at this point. It works fine as-is.

- Jonathan M Davis