DIP 1013, "The Deprecation Process", is now ready for final review. This is a last chance for community feedback before the DIP is handed off to Walter and Andrei for the Formal Assessment. Please read the procedures document for details on what is expected in this review stage:

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

The current revision of the DIP for this review is located here:

https://github.com/dlang/DIPs/blob/1de69e85527aa0e5efea0533c03e8cc732105d02/DIPs/DIP1013.md

In it you'll find a link to and summary of the previous review round. This round of review will continue until 11:59 pm ET on June 21st unless I call it off before then.

Thanks in advance for your participation.

On Thursday, 7 June 2018 at 06:22:04 UTC, Mike Parker wrote:

> @@@DEPRECATED_[version]@@@

This is still ambiguous to me.  Deprecations are done in stages.  For example:

Stage 1 (version 2.081) - Compiler emits deprecation warning
Stage 2 (version 2.086 = 2.081 + 5) - Compiler emits error
Stage 3 (version 2.091 = 2.086 + 5) - Feature is removed.

In @@@DEPRECATED_[version]@@@ does "version" mean "2.081" or "2.086".  That is, is it the version in which the deprecation happened (2.081), or is it the version for which the code must be changed to an error (2.086).  I believe it should be the former, but I have been corrected in the past that it should be the latter.

> On the first release in the deprecation period, the removed symbol(s) SHOULD be removed from any module or package wide list of public functions/booktables/cheatsheets to deemphasize its use.

I don't think that's a very good idea because users, in order to transition their code, will need to refer to the existing documentation in order to understand the semantics of their existing code.  I recommend, instead, requiring the documentation to be annotated with a deprecation notice, and then removed when the feature itself is removed.


I believe it would also make the document easier to read and understand if the stages of deprecation were explicitly documented as an ordered list with each list item having an accompanying description. For example:

Stage 1 - Deprecation
Period - 5 releases (approximately 1 year)
Code is modified to emit a deprecation message.
Documentation is annotated with a deprecation message.

Stage 2 - Error
Period - 5 releases (approximately 1 year)
Code is modified to emit an error.
Documentation is modified to explain that the feature will result in an error.

Stage 3 - Removal
Period - Indefinite
Code is removed.
Documentation is removed.
There may be cases here where the error must remain and the spec updated to explain that the idiom results in an error.  For example: https://github.com/dlang/DIPs/pull/99

Mike

On Thursday, 7 June 2018 at 07:10:37 UTC, Mike Franklin wrote:
> On Thursday, 7 June 2018 at 06:22:04 UTC, Mike Parker wrote:
>
>> @@@DEPRECATED_[version]@@@
>
> This is still ambiguous to me.  Deprecations are done in stages.  For example:
>
> Stage 1 (version 2.081) - Compiler emits deprecation warning
> Stage 2 (version 2.086 = 2.081 + 5) - Compiler emits error
> Stage 3 (version 2.091 = 2.086 + 5) - Feature is removed.
>
> In @@@DEPRECATED_[version]@@@ does "version" mean "2.081" or "2.086".  That is, is it the version in which the deprecation happened (2.081), or is it the version for which the code must be changed to an error (2.086).  I believe it should be the former, but I have been corrected in the past that it should be the latter.

Yep it would be great if the DIP would make this non-ambiguous once and for all.
How about using two different tags?

@@@DEPRECATED_[version]_DOCUMENTATION@@@
@@@DEPRECATED_[version]_REMOVAL@@@

All required actions will still show up in the grep.

BTW it would be great to have a short summary table like the one above in the description of the DIP as a quick reference for future readers of the DIP.

>> On the first release in the deprecation period, the removed symbol(s) SHOULD be removed from any module or package wide list of public functions/booktables/cheatsheets to deemphasize its use.
>
> I don't think that's a very good idea because users, in order to transition their code, will need to refer to the existing documentation in order to understand the semantics of their existing code.  I recommend, instead, requiring the documentation to be annotated with a deprecation notice, and then removed when the feature itself is removed.

The point is to dis-encourage new uses of the deprecated symbol. The symbol will still show up in the symbol search if the users searches for it.
Besides since we have the docarchives, we could even remove the documentation fully as the user will still find it on Google, but it was agreed that this "keep the docstring, but don't promote" is a comprise between both world.

On Friday, 8 June 2018 at 11:27:14 UTC, Seb wrote:

> The point is to dis-encourage new uses of the deprecated symbol.

The deprecation warning from the compiler and annotating the documentation with a deprecation notice will already accomplish that.

Mike

On Thursday, 7 June 2018 at 06:22:04 UTC, Mike Parker wrote:
> DIP 1013, "The Deprecation Process", is now ready for final review. This is a last chance for community feedback before the DIP is handed off to Walter and Andrei for the Formal Assessment. Please read the procedures document for details on what is expected in this review stage:
>
> https://github.com/dlang/DIPs/blob/master/PROCEDURE.md#final-review
>
> The current revision of the DIP for this review is located here:
>
> https://github.com/dlang/DIPs/blob/1de69e85527aa0e5efea0533c03e8cc732105d02/DIPs/DIP1013.md
>
> In it you'll find a link to and summary of the previous review round. This round of review will continue until 11:59 pm ET on June 21st unless I call it off before then.
>

This review round is now complete. Thanks to all who participated!

On Friday, 22 June 2018 at 07:38:04 UTC, Mike Parker wrote:
> On Thursday, 7 June 2018 at 06:22:04 UTC, Mike Parker wrote:
>> DIP 1013, "The Deprecation Process", is now ready for final review. This is a last chance for community feedback before the DIP is handed off to Walter and Andrei for the Formal Assessment. Please read the procedures document for details on what is expected in this review stage:
>>
>> https://github.com/dlang/DIPs/blob/master/PROCEDURE.md#final-review
>>
>> The current revision of the DIP for this review is located here:
>>
>> https://github.com/dlang/DIPs/blob/1de69e85527aa0e5efea0533c03e8cc732105d02/DIPs/DIP1013.md
>>
>> In it you'll find a link to and summary of the previous review round. This round of review will continue until 11:59 pm ET on June 21st unless I call it off before then.
>>
>
> This review round is now complete. Thanks to all who participated!

I know that this comes a bit too late, but when the final version of the DIP is prepared/approved it might be worthwhile to define whether version should start with "v" or not.
I have now seen these three different variants in the wild already:

@@@DEPRECATED_v2.085@@@
@@@DEPRECATED_2.085@@@
@@@DEPRECATED_2.085.0@@@

On Wednesday, June 27, 2018 10:59:35 Seb via Digitalmars-d wrote:
> On Friday, 22 June 2018 at 07:38:04 UTC, Mike Parker wrote:
> > On Thursday, 7 June 2018 at 06:22:04 UTC, Mike Parker wrote:
> >> DIP 1013, "The Deprecation Process", is now ready for final review. This is a last chance for community feedback before the DIP is handed off to Walter and Andrei for the Formal Assessment. Please read the procedures document for details on what is expected in this review stage:
> >>
> >> https://github.com/dlang/DIPs/blob/master/PROCEDURE.md#final-review
> >>
> >> The current revision of the DIP for this review is located here:
> >>
> >> https://github.com/dlang/DIPs/blob/1de69e85527aa0e5efea0533c03e8cc73210 5d02/DIPs/DIP1013.md
> >>
> >> In it you'll find a link to and summary of the previous review round. This round of review will continue until 11:59 pm ET on June 21st unless I call it off before then.
> >
> > This review round is now complete. Thanks to all who participated!
>
> I know that this comes a bit too late, but when the final version
> of the DIP is prepared/approved it might be worthwhile to define
> whether version should start with "v" or not.
> I have now seen these three different variants in the wild
> already:
>
> @@@DEPRECATED_v2.085@@@
> @@@DEPRECATED_2.085@@@
> @@@DEPRECATED_2.085.0@@@

If we're going to be picky about it, personally, I'd prefer

> @@@DEPRECATED_2.085@@@

I see no reason to put a v on it, and the .0 is pointless, because deprecation removals only happen in major versions.

- Jonathan M Davis

On Friday, 22 June 2018 at 07:38:04 UTC, Mike Parker wrote:
> On Thursday, 7 June 2018 at 06:22:04 UTC, Mike Parker wrote:
>> DIP 1013, "The Deprecation Process", is now ready for final review. This is a last chance for community feedback before the DIP is handed off to Walter and Andrei for the Formal Assessment. Please read the procedures document for details on what is expected in this review stage:
>>
>> https://github.com/dlang/DIPs/blob/master/PROCEDURE.md#final-review
>>
>> The current revision of the DIP for this review is located here:
>>
>> https://github.com/dlang/DIPs/blob/1de69e85527aa0e5efea0533c03e8cc732105d02/DIPs/DIP1013.md
>>
>> In it you'll find a link to and summary of the previous review round. This round of review will continue until 11:59 pm ET on June 21st unless I call it off before then.
>>
>
> This review round is now complete. Thanks to all who participated!

I know that I'm super late with this small addition, but as the DIP still hasn't reached its final stage there might be time to incorporate the following nit:

The DIP should clarify at which point the language specification CAN and SHOULD be updated.