Deprecated flags/options

[Stebalien]

It would be nice to support both deprecated and removed flags. Deprecated flags would be hidden (but still work) and "removed" flags would inform the user that the flag has been removed and why.

[lidel]

Need to bump this – adding to maintenance board.

Context

We have a bunch of deprecated command families (object, tar) which are hidden from ipfs --help, but are still accessible + people see them as regular commands in docs which are generated from sources (https://docs.ipfs.io/reference/http/api/, created by generator in https://github.com/ipfs/ipfs-docs/tree/main/tools/http-api-docs).

Implementation

We should add the ability to programmatically indicate three types of commands:

• deprecated
• removed
• experimental (for new stuff, that may get changed)

Having that, --help and generated docs would be augmented to indicate that:

• Helptext would be prefixed with WARNING: EXPERIMENTAL or DEPRECATED
• docs would have separate sections at the end for those types of commands, setting proper devexp expectations.

It could be as simple as adding three bool fields to Command struct, and wiring things up around that.

@schomatis would you be interested in adding this to your queue?
Not a high priority, but would make a big difference for users learning-by-reading-docs or --help when eventually implemented.

[schomatis]

Sure, will take a look at this next week.

[lidel]

This is implemented in:

• feat(Command): add status for the helptext #225

And then leveraged in:

• feat(cmds): document deprecated RPC API commands kubo#8802
• feat: document deprecated RPC API commands ipfs-docs#1086