The deprecation cycle has three phases:

1. Scheduled for deprecation
2. Deprecated
3. Removed

We have several items in Phobos which are currently in phase 1 and possibly some in phase 2 (though I can't think of any off the top of my head). However, as far as I know, no decision has been made as to how long something is typically in phases 1 or 2 before it actually goes to phase 3 and is removed. I know that it's been brought up a couple of times, but I'm not aware of a decision being made. As we do have stuff which is in the deprecation cycle, I think that we need to have at least a rough idea as to how long we intend the average item to be in phases 1 and 2. As such, we need to make a decision. How long will each phase be? 6 months each? Longer? Shorter?

I would think that items which are very new but still end up being put in the deprecation cycle don't have to take as long, and perhaps items which have been around for a long time (such as stuff which is in Phobos 1) should take longer than average. But we need to at least decide on what we want the typical length of time to be.

For simplicity, 6 months for each phase each sounds good to me, but it would be nice for some stuff if it were shorter, since sometimes the old stuff has to be actually removed in order for new functionality to take its place (e.g. std.array has some of its functions being renamed to have InPlace in their names, since they operate in place, but versions which do not operate in place cannot replace them until the old versions have been completely removed). So, 6 months for each phase could be a bit long (since then it would be a year before something actually was removed from Phobos once it entered the deprecation cycle). I really don't know what others might consider reasonable though.

Regardless, I think that we need to make an actual decision on how long stuff will typically be in each phase of deprecation, even if some stuff ends up being removed faster or sticking around longer, depending on its particular circumstances.

- Jonathan M Davis

What if the choice was made that July 4th and January 1st where the days when 2->3 and 1->2 happens. This means we don't track when something was added to what, we just have a predictable schedule. Exceptions could be made for those that must be removed for updates to be made, and maybe that can be on a compiler release basis.

On Fri, May 20, 2011 at 9:59 PM, Jonathan M Davis <jmdavisProg at gmx.com> wrote:
> The deprecation cycle has three phases:
>
> 1. Scheduled for deprecation
> 2. Deprecated
> 3. Removed

That's a nice simple idea, but it's a bit difficult to appreciate that a change effected somewhere in late June immediately gets enacted in a matter of days.

Andrei

On 5/25/11 2:59 PM, Jesse Phillips wrote:
> What if the choice was made that July 4th and January 1st where the days when 2->3 and 1->2 happens. This means we don't track when something was added to what, we just have a predictable schedule. Exceptions could be made for those that must be removed for updates to be made, and maybe that can be on a compiler release basis.
>
> On Fri, May 20, 2011 at 9:59 PM, Jonathan M Davis<jmdavisProg at gmx.com>  wrote:
>> The deprecation cycle has three phases:
>>
>> 1. Scheduled for deprecation
>> 2. Deprecated
>> 3. Removed
> _______________________________________________
> phobos mailing list
> phobos at puremagic.com
> http://lists.puremagic.com/mailman/listinfo/phobos

On Wed, 25 May 2011 22:12:37 +0200, Andrei Alexandrescu <andrei at erdani.com> wrote:

So add a rule for minimum number of days?

> That's a nice simple idea, but it's a bit difficult to appreciate that a change effected somewhere in late June immediately gets enacted in a matter of days.
>
> Andrei
>
> On 5/25/11 2:59 PM, Jesse Phillips wrote:
>> What if the choice was made that July 4th and January 1st where the days when 2->3 and 1->2 happens. This means we don't track when something was added to what, we just have a predictable schedule. Exceptions could be made for those that must be removed for updates to be made, and maybe that can be on a compiler release basis.
>>
>> On Fri, May 20, 2011 at 9:59 PM, Jonathan M Davis<jmdavisProg at gmx.com> wrote:
>>> The deprecation cycle has three phases:
>>>
>>> 1. Scheduled for deprecation
>>> 2. Deprecated
>>> 3. Removed
>> _______________________________________________
>> phobos mailing list
>> phobos at puremagic.com
>> http://lists.puremagic.com/mailman/listinfo/phobos
> _______________________________________________
> phobos mailing list
> phobos at puremagic.com
> http://lists.puremagic.com/mailman/listinfo/phobos


-- 
   Simen

+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.

Andrei

On 25 May 2011 21:12, Andrei Alexandrescu <andrei at erdani.com> wrote:

> That's a nice simple idea, but it's a bit difficult to appreciate that a change effected somewhere in late June immediately gets enacted in a matter of days.
>

Perhaps we could use dateOfChange + n to decide which of those dates it happens with? Eg if n is 1 month there's a maximum of 7 months to wait for the deprecation step, and there's still time to migrate.


> Andrei


-- 
Robert
http://octarineparrot.com/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/phobos/attachments/20110525/50afa1ce/attachment.html>

That should work. But then why not sticking to the current intended scheme? Every release, whatever has aged sufficiently gets deprecated and then removed.

Andrei

On 5/25/11 3:17 PM, Simen Kjaeraas wrote:
> On Wed, 25 May 2011 22:12:37 +0200, Andrei Alexandrescu <andrei at erdani.com> wrote:
>
> So add a rule for minimum number of days?
>
>> That's a nice simple idea, but it's a bit difficult to appreciate that a change effected somewhere in late June immediately gets enacted in a matter of days.
>>
>> Andrei
>>
>> On 5/25/11 2:59 PM, Jesse Phillips wrote:
>>> What if the choice was made that July 4th and January 1st where the days when 2->3 and 1->2 happens. This means we don't track when something was added to what, we just have a predictable schedule. Exceptions could be made for those that must be removed for updates to be made, and maybe that can be on a compiler release basis.
>>>
>>> On Fri, May 20, 2011 at 9:59 PM, Jonathan M Davis<jmdavisProg at gmx.com> wrote:
>>>> The deprecation cycle has three phases:
>>>>
>>>> 1. Scheduled for deprecation
>>>> 2. Deprecated
>>>> 3. Removed
>>> _______________________________________________
>>> phobos mailing list
>>> phobos at puremagic.com
>>> http://lists.puremagic.com/mailman/listinfo/phobos
>> _______________________________________________
>> phobos mailing list
>> phobos at puremagic.com
>> http://lists.puremagic.com/mailman/listinfo/phobos
>
>

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

On 2011-05-25 14:02, Andrei Alexandrescu wrote:
> That should work. But then why not sticking to the current intended scheme? Every release, whatever has aged sufficiently gets deprecated and then removed.

Overall, I prefer that scheme. As soon as you worry about how long has been scheduled for deprecated or deprecated, you have to check how much it's aged anyway. It is true, however, that we don't really have a good way of keeping track of how long something has been deprecated other than simply checking the last few releases after a release to see what has aged enough to move to the next phase for the next release. But that's not particularly hard, and it wouldn't be all that hard for a developer to keep track of it themself if they were the one who was deprecating it. If we wanted to be more organized about it though, we could have a file which listed what was moved to which phase when. Regardless, I think that it makes more sense and is more conducive to progress move stuff from one phase to another based on when it moved into its current phase rather than on a date of the year unrelated to when it was put on the deprecation path. The main question is how long each phase should typically take. If it were only two releases, then there's probably some stuff which is currently scheduled for deprecation which we could now deprecate. If it were 6 releases, then there's probably nothing which should be being deprecated just yet. We need to decide on at least an approximate length of time, since then it's better organized, and we can then give some guarantees to those who ask about it.

- Jonathan M Davis

On 5/25/11 4:20 PM, Jonathan M Davis wrote:
> On 2011-05-25 14:02, Andrei Alexandrescu wrote:
>> That should work. But then why not sticking to the current intended scheme? Every release, whatever has aged sufficiently gets deprecated and then removed.
>
> Overall, I prefer that scheme. As soon as you worry about how long has been scheduled for deprecated or deprecated, you have to check how much it's aged anyway. It is true, however, that we don't really have a good way of keeping track of how long something has been deprecated other than simply checking the last few releases after a release to see what has aged enough to move to the next phase for the next release.

I thought of that for a bit and there are two things we could do:

1. State the date of deprecation in the warning message. Instead of

"Warning: module xxx has been scheduled for deprecation."

we should say:

"Warning: since 2011-xx-xx, module xxx has been scheduled for deprecation."

2. Then, it's difficult for a human being to set in mind dates that are six months ahead. That's what electronic calendars are for. So I propose we define a deprecation czar role who simply uses whatever electronic calendar (google, yahoo...) to enact deprecation. On the day of the deprecation, the czar simply makes the change in the repository. For that we need a self-organized, thorough person. That's why I recommend Jonathan.

>  The main question is how long each phase should
> typically take. If it were only two releases, then there's probably some stuff
> which is currently scheduled for deprecation which we could now deprecate. If
> it were 6 releases, then there's probably nothing which should be being
> deprecated just yet. We need to decide on at least an approximate length of
> time, since then it's better organized, and we can then give some guarantees
> to those who ask about it.

I'd say anything measured in months is reasonable. You aired some numbers at a point that seemed entirely fine to me.


Andrei