Feature: deprecate an option/command

[laggingreflex]

Allow setting deprecated: true for an option or a command, like:

yargs.options({
  oldOption: {type: 'boolean', deprecated: true }
  newOption: {type: 'boolean' }
})

which will show up in help as:

Options:
  --old-option [deprecated]
  --new-option

[bcoe]

@laggingreflex this is a neat idea 👍

[laggingreflex]

Cool. I'll try to implement myself this when I get some time.

Any preferences for the following:

• Key - "deprecated"

• Type - I'm thinking boolean "true/false", but also a string like "Please use --newOption instead"

• Placing of the text -

  Boolean

  1. [deprecated] --option description [type] [default]

  2. --option [deprecated] description [type] [default]

  3. --option description [deprecated] [type] [default]

  4. --option description [type] [default] [deprecated]

  String

  1. ... [deprecated: text] ...

  2. ... [deprecated - text] ...

• Should [type] and [default] be hidden when deprecated is set? I was thinking they should be hidden as they're not gonna be needed anyway (and they'll free up space for the deprecated notice/text), but maybe that decision should be left to the user (they can always remove those fields themselves).

• Should all the deprecated options be pushed below the normal options? I'd prefer this.

Anything else?

PS: Hadn't yet thought about the "command" yet.. will think and comment later.

[mleguen]

@laggingreflex Thanks for digging into this.

deprecated sounds good to me.

A boolean would be easier to implement, but a string would be more practical (nowing how not to use a deprecated option is good, and IMHO the first reason for having such a deprecation notice).

Perhaps you should have a look at existing keys, to try to mimic as much as possible the behavior and naming of an existing key, for homogeneity (I do not have the time right now to do it myself)?

Concerning text placement, I would suggest looking first as how "reference" CLI (GNU tools, git, docker, npm, etc.) do it (if they do it), not to reinvent the wheel.

I would also suggest keeping type and default, as a deprecated option is still valid and usable.

And if we add this, I would definitely want it also for commands!

[laggingreflex]

Was able to finally get this into motion. Please checkout #1559

It implements deprecating just the option for now. Will try to work on command later.

Also, I couldn't find much references in common tools (git, docker, npm) that do it. If you come across it please let me know.

I did find a deprecated option in Docker, but, and I'm not entirely sure, but it didn't seem to mention that option in its --help usage at all. The deprecated option was missing.

However running the command using the deprecated option showed a warning message: "this option has been deprecated". Is that something that should be implemented? I.e. show a warning message when one of the deprecated option is provided in the command-line? (in addition to what I've already done above?)

[shadowspawn]

Looks like this landed in #1624, thanks @laggingreflex.

This issue has not had any activity in over six months.

Feel free to open a new issue if it comes up again, with new information and renewed interest.

Thank you for your contributions.