The deprecation policy requires waiting at least one release since hard deprecation before removing stuff. But the version put in wfDeprecated is the version it was soft deprecated in, so unless you git blame/log, you don't know which version it was hard deprecated in.
We should come up with (and then require) a syntax to indicate when stuff was hard deprecated in.
// Hard-deprecated: 1.32 wfDeprecated( __METHOD__, '1.31' );
Or maybe just make it an unused parameter to the function? ...
As part of the deprecations for T243708, I've been using @deprecated since 1.31 (soft), 1.35 (hard) for example in the doc block, which makes it clear. Is this about including both the soft and hard versions in the documentation, to know when stuff can be removed, or in the wfDeprecated call to be shown in errors (or both?)
I don't really understand why this task is still open either (in its current incarnation). The stable interface policy now/currently indicates that @deprecated is for the soft deprecation and wfDeprecated is for the hard deprecation. So the premise in the task description is actually just wrong now. 😄
A soft deprecation occurs when a developer adds a @deprecated annotation to the documentation comment for a method, function, or class.
A hard deprecation occurs, when a wfDeprecated( __METHOD__, '1.xx' ); call is added to the function or method in question, ...
I think you've missed this bit:
The version number in the wfDeprecated() call MUST match the one in the @deprecated annotation, even if the hard deprecation occurs in a different release.
Hey now, no calling me out after I directly reviewed the policy and magically missed reading the whole paragraph. :^)
@deprecated since 1.31 (soft), 1.35 (hard) for example in the doc block, which makes it clear.
Yes, I think that makes it clear. I also think it's not necessarily easy to find instances of that.
Is this about ...
I think any of the above, based on the originating task. It might be helpful for Jdf to add a list of some pros/cons to options he's considered.
Yeah, finding human-written comments is one of the negatives.
Another is that it'd be nice to write a magical CI check that asserts you're not removing a public function that isn't hard-deprecated in a previous MW release (or warns, as we'd need to over-ride it in some circumstances). An unstructured comment isn't very stable for us to base a regex on.
OTOH, comments are things we can do right now, it can be done async as we fix up after patches after they land (rather than expect everyone to know and immediately switch to that new system), and changing the method signature of wfDeprecated is a pain.