DIP 1013 is titled "The Deprecation Process".

https://github.com/dlang/DIPs/blob/d8f6bfa1810c9774bd7d3b3dc6a7a6776ed5e17e/DIPs/DIP1013.md

All review-related feedback on and discussion of the DIP should occur in this thread. The review period will end at 11:59 PM ET on April 26 (3:59 AM GMT), or when I make a post declaring it complete.

At the end of Round 1, if further review is deemed necessary, the DIP will be scheduled for another round. Otherwise, it will be queued for the formal review and evaluation by the language authors.

Please familiarize yourself with the documentation for the Community Review before participating.

https://github.com/dlang/DIPs/blob/master/PROCEDURE.md#community-review

Note that you can always see the schedule for this and other DIPs that have left Draft Review at:

https://calendar.google.com/calendar/b/1?cid=c29jaWFsQGRsYW5nLm9yZw

Thanks in advance to all who participate.

Destroy!

On Monday, 2 April 2018 at 07:05:45 UTC, Mike Parker wrote:
> DIP 1013 is titled "The Deprecation Process".
>
> https://github.com/dlang/DIPs/blob/d8f6bfa1810c9774bd7d3b3dc6a7a6776ed5e17e/DIPs/DIP1013.md

I think there should be some clarification on the stages of deprecation.  For example, something like this:

Stage 1: T0 - Start of deprecation
  1. The deprecated feature is added to the Deprecated Features page to notify the public that a decision has been made to deprecate the feature.
  2. Pull requests are submitted to update relevant sections of the documentation notifying readers that the feature has been deprecated.
  3. Pull requests are submitted to remove all usages of the deprecated feature from DLang repositories.
  4. Pull requests are submitted to cause the compiler to emit deprecation messages for any usage of the deprecated feature, and to update the Deprecated Features page with the release version of this change.  A changelog entry is also required at this time.

Stage 2: T0 + 5 non-patch releases
  1. Pull requests are submitted to cause the compiler to emit error messages for any usage of the deprecated feature, and to update the Deprecated Features page with the release version of this change.  A changelog entry is also required at this time.

Stage3: T0 + 10 non-patch releases
  1. Pull requests are submitted to remove all knowledge of the deprecated feature from both the documentation and the implementation.  The Deprecated Features page is updated with the release version of this change.  A changelog entry is also required at this time.

> In order to facilitate on schedule deprecations, a comment of the format @@@DEPRECATED_[version]@@@ should be added to the top of the code to be removed/disabled.

Is `[version]` the version in which the deprecation took place, or the future version in which the next stage is to take place.  For example, if I'm deprecating a feature in 2.080, should `[version]` be 2.080, or 2.085 (the version in which the features is changed to an error)?

Mike

On Monday, 2 April 2018 at 07:05:45 UTC, Mike Parker wrote:
> DIP 1013 is titled "The Deprecation Process".
>
> https://github.com/dlang/DIPs/blob/d8f6bfa1810c9774bd7d3b3dc6a7a6776ed5e17e/DIPs/DIP1013.md

I've been thinking about the deprecation schedule being measure in terms of releases, and I don't like it. How was the 10-version schedule determined anyway; probably because it equated to 2 years under the current release schedule (1 year as a deprecation warning, 1 year as an error).  So time is the intrinsic impetus.  If we were to move to a schedule of releases every 6 months, would that require a deprecation period of 5 years? I sure hope not.  Or, if we were to move to a schedule of releases every month, would the deprecation period be only 10 months?  Cool!

I suggest making it "a minimum of 2 years and a maximum of 10 releases", or something of that nature.

Mike

On Wednesday, April 18, 2018 11:23:49 Mike Franklin via Digitalmars-d wrote:
> On Monday, 2 April 2018 at 07:05:45 UTC, Mike Parker wrote:
> > DIP 1013 is titled "The Deprecation Process".
> >
> > https://github.com/dlang/DIPs/blob/d8f6bfa1810c9774bd7d3b3dc6a7a6776ed5e 17e/DIPs/DIP1013.md
> I've been thinking about the deprecation schedule being measure in terms of releases, and I don't like it. How was the 10-version schedule determined anyway; probably because it equated to 2 years under the current release schedule (1 year as a deprecation warning, 1 year as an error).  So time is the intrinsic impetus. If we were to move to a schedule of releases every 6 months, would that require a deprecation period of 5 years? I sure hope not.  Or, if we were to move to a schedule of releases every month, would the deprecation period be only 10 months?  Cool!
>
> I suggest making it "a minimum of 2 years and a maximum of 10 releases", or something of that nature.

I'd be totally fine with something in there indicating that the goal was to have a symbol deprecated and documented for approximately one year and deprecated and undocumented for approximately a year and that 10 releases is the number chosen on the assumption that we have a release approximately every month with the idea that releases would occasionally be late (hence 10 instead of 12). I certainly don't want the deprecation cycle to change much time-wise. Whatever the release schedule is, the deprecation schedule should be approximately two years long.

In many ways I much prefer the time-based deprecations, because it's easier to manage and know when in time a deprecated symbol is going away, but based on a recent discussion on that, most everyone else involved preferred release-based deprecations - hence why this DIP uses releases. Regardless, if the consistency or frequency of our releases changes, then the number of releases to have something deprecated is definitely going to need to change. We arrived at the current two year deprecation cycle after a lot of discussions and adjustments to it in the past, and I don't see a good reason to change it now. It balances keeping symbols around long enough to give everyone plenty of time to update and actually getting rid of symbols when appropriate, instead of leaving them around permanently as cruft. Reducing the length will cause problems for those who don't update frequently, and increasing it will just make it harder to improve Phobos and would allow symbols that we want to get rid of to cause us problems for longer.

On a side note, I would _really_ hate to see us go to a six month release as has occasionally been discussed. As someone who occasionally commits new functionality and fixes to Phobos, I'd very much like to have access to those commits in a reasonable timeframe instead of waiting half a year for them.

- Jonathan M Davis

On Thursday, April 05, 2018 14:42:56 Mike Franklin via Digitalmars-d wrote:
> On Monday, 2 April 2018 at 07:05:45 UTC, Mike Parker wrote:
> > DIP 1013 is titled "The Deprecation Process".
> >
> > https://github.com/dlang/DIPs/blob/d8f6bfa1810c9774bd7d3b3dc6a7a6776ed5e 17e/DIPs/DIP1013.md
> I think there should be some clarification on the stages of deprecation.  For example, something like this:
>
> Stage 1: T0 - Start of deprecation
>    1. The deprecated feature is added to the Deprecated Features
> page to notify the public that a decision has been made to
> deprecate the feature.
>    2. Pull requests are submitted to update relevant sections of
> the documentation notifying readers that the feature has been
> deprecated.
>    3. Pull requests are submitted to remove all usages of the
> deprecated feature from DLang repositories.
>    4. Pull requests are submitted to cause the compiler to emit
> deprecation messages for any usage of the deprecated feature, and
> to update the Deprecated Features page with the release version
> of this change.  A changelog entry is also required at this time.
>
> Stage 2: T0 + 5 non-patch releases
>    1. Pull requests are submitted to cause the compiler to emit
> error messages for any usage of the deprecated feature, and to
> update the Deprecated Features page with the release version of
> this change.  A changelog entry is also required at this time.
>
> Stage3: T0 + 10 non-patch releases
>    1. Pull requests are submitted to remove all knowledge of the
> deprecated feature from both the documentation and the
> implementation.  The Deprecated Features page is updated with the
> release version of this change.  A changelog entry is also
> required at this time.

As far as the library goes, this is not how it currently works, and I _really_ don't want it to start working that way now. Currently, we have one year of a symbol being deprecated and documented, and one year of a symbol being deprecated and undocumented. The DIP follows that except that it uses releases instead of years with the idea that we'll get approximately 5 major releases in a year (with 1 every two months, the number should be more like 12, but since we're going to slip occasionally, saying 10 instead 12 makes it so that we'll hit approximately the right now, and it favors removing slightly faster over being stuck with a symbol slightly longer due to some releases being delayed).

I see no reason to add a changelog entry when the symbol becomes undocumented, and I see no reason to start making anything errors. That's not how deprecations work. Unless you compile with -de, using a deprecated symbol only prints a message - it's not even a warning. So, it has zero effect on compilation except that any function which uses a deprecated symbol without being marked as deprecated itself will result in deprecation messages being printed. No code fails to compile, and -w doesn't change anything. Years ago, we specifically made it so that deprecated didn't generate errors, because having it generate errors made it useless. It immeditately broke code any time you deprecated something and wasn't much better than simply removing the symbol. The current behavior of -deprecated is worlds better, and both the current deprecation policies and those outlined in the DIP (which aside from the change from years to releases is more or less the same as what happens now for Phobos) work quite well with how -deprecated works.

Adding a changelog entry when the symbol is deprecated and when it is removed seem plenty.

Overall, this DIP is simply formalizing what we do now with deprecations for Phobos, and I'd very much like it to stay that way. Clarifying the deprecation process is fine with me, but what we've been doing (as far as the library goes anyway) has largely been working, and I don't want it to be changed without a really good reason (especially since I'm the main person mananging it).

As for deprecations in the language itself, that's never been particularly consistent or formalized. This seems to do that fairly well by essentially saying that language features should be deprecated for the same length as symbols in the library. It's just that the language feature doesn't get undocumented halfway through the deprecation cycle, and the process of what you have to do beyond actually deprecating the feature is a bit different, because there are other things that have to be considered (e.g. updating the spec).

> > In order to facilitate on schedule deprecations, a comment of the format @@@DEPRECATED_[version]@@@ should be added to the top of the code to be removed/disabled.
>
> Is `[version]` the version in which the deprecation took place, or the future version in which the next stage is to take place. For example, if I'm deprecating a feature in 2.080, should `[version]` be 2.080, or 2.085 (the version in which the features is changed to an error)?

As I said before, it's never changed to an error. The DIP quite specifically never does that, and really I don't think that it should. However, the point about which release to mention in the message not being clear is a good one. What I've typically been doing has been to document the release that the symbol is going to be removed from the documentation, and then when I undocument the symbol, I add a non-ddoc comemnt with a note about when it's actually scheduled to be removed. We haven't typically been putting the date of removal (either from the documentation or the library) in the deprecation message itself.

However, putting the date that the documentation is going to be removed in the documentation has proven to be confusing. One result is that often, folks have mistakenly thought that the deprecation cycle was one year instead of two. As such, I think that going forward, we should be the release for removal in the documentation (and the deprecation message, since the DIP formalizes that it goes there too). It should be fairly easy to figure out when a symbol should be undocumented based on the release that it's marked for removal. You just subtract five. And if in a particular case, we need to adjust the removal schedule and thus undocument the symbol at a release other than removal - 5, then we can just add a note in a non-ddoc comment.

- Jonathan M Davis

On Monday, April 02, 2018 07:05:45 Mike Parker via Digitalmars-d wrote:
> DIP 1013 is titled "The Deprecation Process".
>
> https://github.com/dlang/DIPs/blob/d8f6bfa1810c9774bd7d3b3dc6a7a6776ed5e17 e/DIPs/DIP1013.md
>
> All review-related feedback on and discussion of the DIP should occur in this thread. The review period will end at 11:59 PM ET on April 26 (3:59 AM GMT), or when I make a post declaring it complete.
>
> At the end of Round 1, if further review is deemed necessary, the DIP will be scheduled for another round. Otherwise, it will be queued for the formal review and evaluation by the language authors.
>
> Please familiarize yourself with the documentation for the Community Review before participating.
>
> https://github.com/dlang/DIPs/blob/master/PROCEDURE.md#community-review
>
> Note that you can always see the schedule for this and other DIPs that have left Draft Review at:
>
> https://calendar.google.com/calendar/b/1?cid=c29jaWFsQGRsYW5nLm9yZw
>
> Thanks in advance to all who participate.
>
> Destroy!

Overall, I think that this DIP is solid. As far as Phobos goes, it follows essentially the same process that we do now, but it formalizes and clarifies a few things. The big change is going from using dates to specific releases for the deprecation cycle, and that was recently agreed upon. We've been doing one year as deprecated and documented and one year as deprecated and undocumented prior to removal, and the DIP matches that on the assumption that we're going to have 5 - 6 major releases a year. So, on the whole, I very much approve of this DIP.

The only tweaks that I would suggest are:

1. Clarify that it's the removal release in the messages, not the one where the symbol is undocumented. The DIP is not clear on that. In the documentation, I've historically been using the date that the symbol would be undocumented, and that has caused confusion about the length of the deprecation cycle. Using the removal release would be clearer, and subtracting by five to determine the release for undocumenting the symbol is easy.

2. Somewhere, it should state that the goal is for the typical deprecation cycle for a symbol to last approximately two years and that the number of releases was picked on the assumption that we would have approximately 5 - 6 major releases a year. So, if at some point in the future, the typical number of releases in a year changes for whatever reason, the number of releases of the deprecation cycle should then be adjusted so that the deprecation cycle stays approximately two years long.

- Jonathan M Davis

On Wednesday, 18 April 2018 at 12:28:59 UTC, Jonathan M Davis wrote:
>> > In order to facilitate on schedule deprecations, a comment of the format @@@DEPRECATED_[version]@@@ should be added to the top of the code to be removed/disabled.
>>
>> Is `[version]` the version in which the deprecation took place, or the future version in which the next stage is to take place. For example, if I'm deprecating a feature in 2.080, should `[version]` be 2.080, or 2.085 (the version in which the features is changed to an error)?
>
> As I said before, it's never changed to an error. The DIP quite specifically never does that, and really I don't think that it should.

The current process, as I understand it for language features, is the deprecated feature is a deprecation message for a year, and then an error for a year.  After 2 years of being deprecated it is removed.  Perhaps you were only referring to a deprecated library feature.

Mike

On Wednesday, April 18, 2018 12:48:18 Mike Franklin via Digitalmars-d wrote:
> On Wednesday, 18 April 2018 at 12:28:59 UTC, Jonathan M Davis
>
> wrote:
> >> > In order to facilitate on schedule deprecations, a comment of the format @@@DEPRECATED_[version]@@@ should be added to the top of the code to be removed/disabled.
> >>
> >> Is `[version]` the version in which the deprecation took place, or the future version in which the next stage is to take place. For example, if I'm deprecating a feature in 2.080, should `[version]` be 2.080, or 2.085 (the version in which the features is changed to an error)?
> >
> > As I said before, it's never changed to an error. The DIP quite specifically never does that, and really I don't think that it should.
>
> The current process, as I understand it for language features, is the deprecated feature is a deprecation message for a year, and then an error for a year.  After 2 years of being deprecated it is removed.  Perhaps you were only referring to a deprecated library feature.

I'm referring specifically to the library. As far as I can tell, the language hasn't had a real process, and it's been handled differently practically every time, so adding process would be an improvement. I think that it's been very typical for anything that's been deprecated in the language to stay that way for a long time. And I definitely don't think that they've been anywhere near as organized as what you're suggesting (though they may very well have gotten better about it recently). Either way, I don't have strong feelings about how the language itself is handled, though a similar length for the deprecation process makes sense.

Having it be an error for the language makes some sense, because it's not necessarily the case that once it's gone, the code won't compile anymore (depending on the feature being deprecated), but for the library, that would just cause problems, and we don't really have a way to make it happen even if we wanted to. It's going to be pretty rare that removing a symbol from Phobos is going to result in code compiling that didn't compile while the deprecated symbol was in place, and turning deprecation messages into errors has the same effect as removing the symbol as far as code breakage goes.

If the compiler devs want to do something differently with the language itself, I don't really care so long as it's reasonable. But I'm very opinionated about what happens with the library, in part, because I'm essentially the person in charge of managing deprecations there.

- Jonathan M Davis

On Monday, 2 April 2018 at 07:05:45 UTC, Mike Parker wrote:
> [snip]

I like this. A goto-reference as of how and when to deprectate and remove.

About the concerns that depractation period being measured by releases could fluctate the interval, I definitely would have agreed in autumn 2016. But now we have the release progress in place so I think it will go predictably enough.

Nonetheless, I think that maintainers must always retain the liberty to disregard these rules when there's a very good reason. If there, for example, starts to be much larger slips in release schelude again they should be able to go ahead and remove stuff early.

On Wednesday, 18 April 2018 at 12:40:44 UTC, Jonathan M Davis wrote:
> 2. Somewhere, it should state that the goal is for the typical deprecation cycle for a symbol to last approximately two years and that the number of releases was picked on the assumption that we would have approximately 5 - 6 major releases a year. So, if at some point in the future, the typical number of releases in a year changes for whatever reason, the number of releases of the deprecation cycle should then be adjusted so that the deprecation cycle stays approximately two years long.

At the moment we have a clear bi-monthly release cycle (1st of every odd month).

In the long-run I'd like to transition to one major releases every 6 months and strictly non-breaking, non-deprecating point releases every 2 months. So far there wasn't much interest in the necessary development adjustments though.
https://forum.dlang.org/thread/drcekmxvfszpwifbukzk@forum.dlang.org