Notation CLI guideline and CLI spec template

[yizha1]

What is the areas you experience the issue in?

Notation CLI

What is not working as expected?

The Notation CLI specs are stored under https://github.com/notaryproject/notation/tree/main/specs as following:

• The entrance of notation CLI commands: notation-cli.md
• Spec for each command: https://github.com/notaryproject/notation/tree/main/specs/commandline

Currently, most of the CLI specs covers the following content:

- Description (Mandatory)
- Outline (Mandatory)
- Feature specific (case by case)
- Usage (Mandatory)

However, there are other valuable information is missing, for example:

• Usage of all the options
• Output
• Error handling

Besides the above, there are other general guidelines for CLI commands missing.

What did you expect to happen?

Create two CLI documents: one for CLI guideline, and another for CLI spec template. The two documents will be store under https://github.com/notaryproject/notation/tree/main/specs/, and linked it to contributing guide.

The CLI spec will look like:

- Description (Mandatory)
- For each available command, including
  - Synopsis (Mandatory)
  - Options (Mandatory)
  - Output (Mandatory)
- Examples

The CLI guideline should cover:

• General patterns:
  • Be consistent with POSIX tools (support piping, work with grep, awk, jq, etc.)
  • Support tab completion for parameter names and values (supported by cobra framework now, but missing document for now)
• Command input conversion
  • Options, for example:
    • avoid mixing common flag name, like --output, --id, --verbose, -d
    • how to specify parameter values, such as key=value
  • CRUD commands: create/update/show/list/delete, add/remove
• Command output convention
  • Commands should support different output types (json, text, table, or other type)
  • Command return value, what for success and what for error (can be used by script to decide whether comment execution is successful)
  • Commands output goes to stdout, errors or others to stderr
• Environment variables
• Error Handling
  • Error Message
    • A general pattern is provided here, keep it in mind when you write an error message.
      • What the error is.
      • Why it happens
      • What users need to do to fix it.
    • Error message format
• Verbose/debug: log debug output
  • log message format

How can we reproduce it?

N/A, this is for document

Describe your environment

N/A, this is for document

What is the version of your Notation CLI or Notation Library?

N/A, this is for document

[yizha1]

Looking for comments: @FeynmanZhou, @toddysm, @iamsamirzon and @vaninrao10