Next in Review Queue: The New std.path

[Jonathan M Davis]

On Friday 15 July 2011 04:13:35 Nick Sabalausky wrote:
> "dsimcha" <dsimcha at yahoo.com> wrote in message
> news:ivo271$1fu0$1 at digitalmars.com...
> 
> > 3.  All the stuff from the old std.path should be "scheduled for
> > deprecation".  Deprecating stuff breaks people's build processes and
> > should only be done after adequate warning.  I don't know a good way to
> > implement this for enums and aliases, though, which I guess begs the
> > question of whether DMD should support soft deprecation.
> 
> Isn't that what -d is for?

The way that deprecation is supposed to work is in three stages:

1. Scheduled for deprecation.
2. Deprecated.
3. Removed.

In stage 1, users are notified that a symbol is going to be deprecated, but it 
is not yet deprecated. This gives them time to alter their code accordingly 
before they will have to build with -d. In stage 2, the symbol is actually 
deprecated with the deprecated keyword, and -d is required to compile code 
which uses that symbol. If the user has not yet altered their code, then they 
will have to alter their build scripts to use -d. Finally, in stage 3, the 
deprecated symbol is removed.

In stage 1, when a symbol is scheduled for deprecation, the documentation is 
altered to reflect that, and ideally a message would be printed out if it's 
used so that programmers will be better notified about the impending 
deprecation. However, since the only tool we have for that at the moment is 
pragmas, only entire modules and templated functions or types or types can 
have such messages (since otherwise the message would print regardless of 
whether you use the symbol). A number of complaints have arisen about these 
messages, however  (a number were introduced in 2.054 - both for stuff which 
had already scheduled for deprecation and for stuff which was just scheduled 
for deprecation). So, we may end up ditching the pragma messages. I don't 
know.

In either case, Walter has been pretty adamant about not breaking users' code 
without notice. So, immediately deprecating something (thereby breaking their 
code - even if all it takes is changing their build scripts to use -d) is not 
generally acceptable - hence the "scheduled for deprecation" phase.

The current plan is that stage 1 and stage 2 both take 6 months each, but we 
may adjust that depending on what's being changed (e.g.g smaller changes or 
changes of recently added stuff may take less time).

- Jonathan M Davis