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.
