[phobos] Decision on length of deprecation cycle

[Jonathan M Davis]

On 2011-05-25 13:28, Andrei Alexandrescu wrote:
> +phobos at puremagic.com
> 
> On 5/25/11 3:25 PM, Jesse Phillips wrote:
> > I don't consider stage 1 as important, if nothing more than it is
> > strange to say that something will be deprecated, but it isn't
> > deprecated right now, so don't use it.
> 
> It gives people time to migrate code on their own schedule.

Yes. And that's particularly important with larger changes such as moving from 
std.date to std.datetime. Walter is big on avoiding breaking changes, and 
while I think that he is overly worried about making changes some of the time, 
I do think that we need to strive to make what changes we make as painless as 
reasonably possible. And as Phobos becomes more mature and is used more, it 
will become that much more important to avoid breaking changes. We should 
probably try and revamp and change what we know is going to need it earlier 
rather than later, and as those problems are resolved, we should hopefully 
reach the point where breaking changes are needed fairly rarely. The review 
process for new modules should help avoid a lot of those problems as well by 
ensuring appropriate levels of code quality and consistency with Phobos 
conventions prior to actually adding the code to Phobos. In any case, we do 
need to make sure that we don't cause much in the way of breaking changes and 
use the deprecation cycle to ease in changes when we need to.

As a side note, it would be fantastic if deprecated could be improved to not 
only take a message to print when the deprecated item is used (instead of 
having to use a pragma) but so that we could mark an item as scheduled for 
deprecation. As it is, unless you deprecate an entire module at once, any 
function or type that you schedule for deprecation or outright deprecate needs 
to be templatized with the pragma inside it or the pragma will print 
regardless of whether that symbol is ever used. That sometimes requires 
templatizing no-templatized functions and it doesn't work at all for anything 
that you can't templatize - such as variables or enums. Perhaps

deprecated <- deprecated, no message
deprecated("msg") <- deprecated with a message
deprecated("msg", hard) <- same thing
deprecated("msg", soft) <- scheduled for deprecation with message.

I know that it's been suggested before, and perhaps that's not the best syntax 
for it, but it would definitely be cleaner if we didn't have to use pragma to 
generate deprecation messages.

- Jonathan M Davis