Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Proposal for 1.x.x deprecations API #1

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Proposal for 1.x.x deprecations API #1

wants to merge 7 commits into from

Conversation

shama
Copy link
Member

@shama shama commented Feb 15, 2016

@Ryuno-Ki
Copy link

Ryuno-Ki commented Mar 5, 2016

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
Copy link
Member

cowboy commented Mar 17, 2016

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
Copy link

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
Copy link

schmod commented Mar 21, 2016

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
Copy link

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
Copy link

👍 for @shama picked it up again.

All deprecation notifications can be disabled with a cli flag:

```shell
grunt foo --hide-deprecations
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member

vladikoff commented Feb 14, 2018 via email

Base automatically changed from master to main March 22, 2021 15:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants