digitalmars.D - DIP 1013--The Deprecation Process--Final Review
- Mike Parker (12/12) Jun 06 2018 DIP 1013, "The Deprecation Process", is now ready for final
- Mike Franklin (39/44) Jun 07 2018 This is still ambiguous to me. Deprecations are done in stages.
- Seb (17/40) Jun 08 2018 Yep it would be great if the DIP would make this non-ambiguous
- Mike Franklin (5/6) Jun 08 2018 The deprecation warning from the compiler and annotating the
- Mike Parker (2/13) Jun 22 2018 This review round is now complete. Thanks to all who participated!
- Seb (9/29) Jun 27 2018 I know that this comes a bit too late, but when the final version
- Jonathan M Davis (5/36) Jun 27 2018 I see no reason to put a v on it, and the .0 is pointless, because
- Seb (6/26) Jul 09 2018 I know that I'm super late with this small addition, but as the
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.
Jun 06 2018
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
Jun 07 2018
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: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.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.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 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.
Jun 08 2018
Mike Franklin <slavo5150 yahoo.com> 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
Jun 08 2018
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!
Jun 22 2018
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: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.0DIP 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!
Jun 27 2018
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:If we're going to be picky about it, personally, I'd preferOn Thursday, 7 June 2018 at 06:22:04 UTC, Mike Parker wrote: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.0DIP 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!DEPRECATED_2.085I 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
Jun 27 2018
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: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.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!
Jul 09 2018