DIP 1013--The Deprecation Process--Final Review

[Seb]

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.