Framework: Adding a deprecation helper #5069
Conversation
data/index.js
Outdated
| 'Deprecated: `select` now accepts only a single argument: the reducer key. ' + | ||
| 'The return value is an object of selector functions.' | ||
| ); | ||
| deprecated( 'Calling select with multiple arguments', '2.4', undefined, 'Gutenberg' ); |
There was a problem hiding this comment.
Have you consider using an object with named params instead? It would help to avoid passing undefined and make it easier to reason which param does what when reading code.
There was a problem hiding this comment.
Yes, I was hesitant because the calling side will be more verbose. I don't have a strong opinion though. Happy to update with what y'all think is best.
There was a problem hiding this comment.
Yes, it'd produce more work for developers :(
There was a problem hiding this comment.
I agree with passing an object param rather than positional params. WordPress is rife with functions that contain positional parameters which are hard to remember the order of. In some cases a positional parameter has become deprecated requiring that it be change to $deprecated in the function signature, and requires always passing null in each call. Using an object is more flexible and will allow adding additional parameters in the future as required.
| */ | ||
| import { deprecated } from '../deprecation'; | ||
|
|
||
| describe( 'deprecated', () => { |
There was a problem hiding this comment.
Love those tests, they are so fun to read and perfectly explain all the logic hidden in the tested method ❤️
There was a problem hiding this comment.
I love this PR, it provides a unified way to handle deprecation logic. It gives a very user-friendly message with all required details and is nicely covered with tests. Great work @youknowriad. I had one concern regarding params, but I'm aware that there are pros and cons of both approaches. Just wanted to share my feeling from the first pass on this code.
This is my concern with the approach here, and the obvious alternative of changing to an object shape makes me start to wonder if we ought to just simplify this to: deprecated( version, message )...Even if it means losing some of the automatic consistency. Maybe message could look like:
|
|
I do think having a helper with just the version and the message doesn't bring too much value in term of consistency but I agree with the arguments issue we have right now. What do you all think with an update API like this: The feature is the only mandatory argument, it makes sense to leave it as a separate argument and the others are moved to an object. |
… of the deprecated helper
|
Nice, even better than before 👍 |
|
I don't particularly love the fact that the developer needs to understand how the strings are concatenated into the final output sentence. If we were to have recommendations as part of the API, I think it might be less confusing to have developer provide these as full sentences, then output like:
The biggest win I'd see in having a helper like this is enforcing a predictable timeline for removal. Currently nothing will happen after e.g. v2.4 or v2.5 is released. I might imagine one of:
|
|
@aduth Makes sense to me.
I thought it could be manual at first but would be great to provide an automatic way to do so.
I like this format and agree with your statement. Feel free to update the helper. I could also circle back later. Thanks |
That's a really interesting idea 👍 |
|
I think the automation could be achieved as part of a version-bump handler which performs all of the current tasks necessary for a version bump, plus updating a With the object format, it's a little more difficult, but if we had it as an argument: The AST selector could look something like: Or we could just create a custom rule which extracts the plugin version from e.g. |
This PR adds a
deprecatedfunction to produce a consistent warning message when deprecating features in WordPress and WordPress plugin.You can provide: