Provide a deprecation mechanism based upon aliasing

[Rob Vesse]

Command line interfaces often evolve over time. In my experience early releases often place all commands at the top level and as later releases happen commands get moved into groups in order to better organise them. However in terms of user experience this can often be a breaking change.

One way around this is to use the aliasing mechanism to redirect the old names to the new locations. However if you do this users are unaware that this is happening and so if you later decide to drop these aliases users still end up with a jarring transition.

A nicer way to handle this would be to provide a specific deprecation mechanism based upon aliasing. The idea of being that you could explicitly declare a deprecation. This will be automatically translated into a alias but with the added functionality that a warning message about the deprecation would be presented to users. Deprecation could also be declared such that a flag can be set to indicate whether a deprecation is a warning or an error. When set to error using a deprecated command name would result in a parsing failure.

Such a mechanism would allow people to release command name changes in a gradual manner. So the first release where a command name is changed you would mark the old name as deprecated with a redirection to new name and users would see appropriate warnings. In a subsequent release you could mark that deprecation as being in error and users would then be forced to adjust to the new name