Improving deprecation management
Jonathan M Davis
jmdavisProg at gmx.com
Wed Nov 13 11:02:08 PST 2013
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
More information about the Digitalmars-d
mailing list