Implement deprecate API and deprecate APIs #1625
Conversation
lib/grunt/deprecate.js
Outdated
| var grunt = require('../grunt'); | ||
|
|
||
| function deprecate(obj, property, message) { | ||
| if (Array.isArray(obj)) { |
There was a problem hiding this comment.
Instead of this "if array" logic, I'd just call .forEach on the array of to-be-deprecated items on line 38.
| } | ||
| var logged = false; | ||
| function warn() { | ||
| var hideDeprecation = grunt.option('hide-deprecations'); |
There was a problem hiding this comment.
Can you look at grunt.option('hide-deprecations') at the top of deprecate and just return there if it's true?
There was a problem hiding this comment.
I put it in the warn to try to catch later calls to grunt.option('hide-deprecations', true). So you could have the option to potentially hide warnings from other modules but not your own (prevent your team from using deprecated APIs but can't fix deprecations in other APIs).
But I might be complicating it unnecessarily, let me know and I'll move it out.
lib/grunt/deprecate.js
Outdated
| configurable: true, | ||
| set: function(val) { | ||
| warn(); | ||
| orig = val; |
There was a problem hiding this comment.
Maybe don't call the value orig if it can be changed? 😁
lib/grunt/deprecate.js
Outdated
| } | ||
| module.exports = deprecate; | ||
|
|
||
| deprecate([ |
There was a problem hiding this comment.
It might make sense to call deprecate in a different file than where it's defined... but perhaps I'm overthinking things!
There was a problem hiding this comment.
Separating the API from the apply makes sense to me. I moved the deprecations into their own file called deprecations.js.
|
Overall, makes sense to me, Thanks, @shama for doing this. I do like the idea, though, of first implementing the warnings in verbose mode only, then in a subsequent minor release, in non-verbose mode, and then finally removing the exposed methods in a future major release. However, I'm not sure how much I care :) |
Deprecations live separately from deprecate API Dont change original val on set deprecate doesnt accept array, just iterate and call deprecate
| obj: grunt.util, | ||
| property: 'repeat', | ||
| message: 'grunt.util.repeat has been deprecated. Please use ' + | ||
| '`new Array(num + 1).join(str || \' \')` or another library.' |
There was a problem hiding this comment.
lol, didn't know this existed
|
Code looks good, but I will need to run this locally to make sure it deprecates. I Will try to get to that soon |
| "glob": "~7.0.0", | ||
| "grunt-cli": "~1.2.0", | ||
| "grunt-known-options": "~1.1.0", | ||
| "grunt-legacy-log": "~1.0.0", | ||
| "grunt-legacy-util": "~1.0.0", | ||
| "iconv-lite": "~0.4.13", | ||
| "js-yaml": "~3.5.2", | ||
| "lodash": "~4.17.5", |
There was a problem hiding this comment.
Do we really need lodash?
There was a problem hiding this comment.
5 years ago we probably did.
Ref: gruntjs/rfcs#1
This implements an internal deprecations API that displays a warning in the console if one of the deprecated APIs are used.
To hide deprecation warnings, use
--hide-deprecationson the CLI orgrunt.option('hide-deprecations', true)in your Gruntfile.When
--stackorgrunt.option('stack', true)is enabled, the deprecation warnings will print stack traces out to locate the deprecated APIs.The following APIs will be publicly deprecated:
grunt.util._grunt.util.asyncgrunt.util.namespacegrunt.util.hookergrunt.util.exitgrunt.util.toArraygrunt.util.repeatgrunt.file.globgrunt.file.minimatchgrunt.file.findupgrunt.file.readYAMLgrunt.file.readJSONgrunt.eventThe following APIs should be considered for deprecation although there isn't simple alternatives to point people to at this time (help?):
grunt.util.spawngrunt.util.callbackifygrunt.util.kindOfgrunt.util.pluralizegrunt.util.recurseInternally Grunt still uses these deprecated APIs. We should address those deprecation warning internally first too.All deprecations have now been fixed in this PR.
This can be released on next minor release as it is backwards compatible but only adds a new behavior. Removing the deprecated APIs will happen on the next major release.