Document CLI design guidelines

Similar to https://docs.meltano.com/contribute/api#api-v2-design-guidelines we should have clearly defined guidelines for creating/updating the meltano cli. How to structure, organize, and even name new CLI additions is a frequent source of contention and a stumbling block during iterations and builds.

I think it’s worth calling out that it’s OK that our CLI’s inconsistent right now, and not all meltano commands will follow this style guide immediately. However, I think we need a guide in place (even if it’s an aspirational one) moving forward so that we can start aiming for a consistent CLI experience for users, and to have a consistent UX style guide in place during feature planning.

This doc should cover:

• Desired verb/command linkage and structure
• Expected common sub-command’s and options
• Expected common output formats
• Use of short and long flags
• Abbreviations
• Global vs argument level flags
• Reusing short flags
• Flag aliases
• Consistent definition of Groups, Commands, Sub-commands, Arguments, and Options
• Expected help and usage
• Doc style guidelines for how to style examples and usage of:
  • Optional arguments/options/flags
  • Required items
  • Mutually exclusive args
  • Arguments that can repeat
• What belongs the cli module (i.e.meltano/cli/the_command.py) and what belongs in meltano.core.
• Phrasing guidelines for command Deprecation and Preview/Beta commands.

[pandemicsyn]

@tayloramurphy I was thinking sending along a PR and then letting y’all edit/bikeshed it during the review might be easiest. Since it would let folks thread on the actual things in question.

Quick edit to follow up on that, i’d probably use schedule and jobs since I’d hope those additions (and refactor in the case of schedule) would be good jump of points , at least for the general structure/layout - since we did those relatively recently.

[pandemicsyn]

Do you have a preference on discussing the spec here or in a specific PR? Similar to what you did for the API discussion I think coming out with a strong proposal will get us 90% of the way there and we can bikeshed over a few points.

@tayloramurphy I was thinking sending along a PR and then letting y’all edit/bikeshed it during the review might be easiest. Since it would let folks thread on the actual things in question.