DIP 1013--The Deprecation Process--Final Review

[Mike Franklin]

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