Proposal for 1.x.x deprecations API

[shama]

Rendered

[Ryuno-Ki]

Concerning the unresolved question:

Easier way to deprecate every function on grunt.util._.* and grunt.util.async.* without having to list every function?

I could image looping over all keys of an object (here: grunt.util._) and check on functions.

However, since you proposed this log message:

WARN: grunt.util._ has been deprecated. Please use lodash directly: https://gruntjs.com/migration-guide#lodash

Either the website needs to follow a certain convention (to concat the URL on the flay) or you'll need to deal with every function separately.

[cowboy]

I don't think deprecate needs to be exposed as grunt.deprecate. It can just be an internal lib that's used inside of grunt.

It might be nice to add a cli flag and exposed method to suppress deprecation messages.

It would be nice to see an api like this. All the deprecations could be defined in a single file, like lib/grunt/deprecations.js

var grunt = require('../grunt');

deprecate([
  {
    obj: grunt.util,
    property: '_',
    message: 'WARN: grunt.util._ has been deprecated. Please use lodash directly. (etc)',
  },
  ...
]);

An idea:

https://jsfiddle.net/cowboy/944ap427/

[Ryuno-Ki]

I like the way, CSSLint describes rules.

CSSLint.addRule({

    //rule information
    id: "empty-rules",
    name: "Disallow empty rules",
    desc: "Rules without any properties specified should be removed.",
    url: "https://github.com/CSSLint/csslint/wiki/Disallow-empty-rules",
    browsers: "All",
    /* … */

[schmod]

What about a "multi-phased" deprecation process?

Stage 1: Print a deprecation warning in Verbose mode. Add a "strict" mode that treats any deprecated method calls as a fatal error -- this can be used by plugin authors to force their builds to fail hard whenever a deprecated API is called (which would be particularly helpful in an automated CI environment).

Stage 2: Print a deprecation warning in non-verbose mode. Ideally, actively-maintained plugins will have been updated during Stage 1, minimizing the disruption for typical users.

Stage 3: Print a deprecation warning in non-verbose mode. Grunt exits with a fatal error (albeit a descriptive one, letting users know that an API has been removed, rather than dumping a stack trace).

Stage 4: Method is removed entirely.

The timeline for moving methods through these 4 stages would be up for debate. To conform with semver, stages 1/2 could be introduced in a minor release, while stage 3 and 4 would each need to be phased in with a major release.

[Ryuno-Ki]

Sounds good, @schmod.

Actually lo_dash's deprecation warning/info made me aware of Grunt becoming a project of jQuery foundation, leading me to read their blog post, which highlighted this repo :-)

[Ryuno-Ki]

👍 for @shama picked it up again.

[vladikoff]

how about an ENV variable instead of --hide-deprecations? or both

[shama]

I'd vote no because AFAIK we haven't done that with any other Grunt options in the past. People can do grunt.option('hide-deprecations', process.env.GRUNT_HIDE_DEPRECATIONS) in their Gruntfile if needed too.

[vladikoff]

ah yes, that's a good solution!

…

On Feb 14, 2018 15:39, "Kyle Robinson Young" ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In text/0000-deprecations.md <#1 (comment)>: > + +Then if any plugin or Gruntfile uses that API, it will log the message: + +```shell +>> grunt.util._ has been deprecated. Please use lodash directly: https://gruntjs.com/migration-guide#lodash +``` + +If `--stack` is provide, it will display a stack trace to located where the +deprecated API. + +### Disable Deprecation Notices + +All deprecation notifications can be disabled with a cli flag: + +```shell +grunt foo --hide-deprecations I'd vote no because AFAIK we haven't done that with any other Grunt options in the past. People can do grunt.option('hide-deprecations', process.env.GRUNT_HIDE_DEPRECATIONS) in their Gruntfile if needed too. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#1 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAH287G5kQjyQgoWiW_glBLGwzTQF_B8ks5tU0RngaJpZM4HauiJ> .