Skip to content

Commit

Permalink
Clarity for commands vs global options
Browse files Browse the repository at this point in the history
While reviewing the `global options` section in `runtime.md`, it seemed additional clarity
was needed for the `command` and `global options` requirements.

Discussed and worked on wording with @wking via private IRC.

Also adds uppercase RFC 2119 words for this section.

With regard to the statement `Command names MUST not start with hyphens,` the rationale
behind this decision is to "distinguish unrecognized commands from unrecognized options,
and because we are "requiring runtimes to fail-fast for unrecognized commands" [1,2].

`[1]` https://github.com/wking/oci-command-line-api/pull/8/files#r46898167
`[2]` 527f3c6#commitcomment-14835617

Signed-off-by: Mike Brown <brownwm@us.ibm.com>
Reviewed-by: W. Trevor King <wking@tremily.us>
  • Loading branch information
mikebrow authored and wking committed Dec 11, 2015
1 parent 0d0c8db commit e9a6625
Showing 1 changed file with 5 additions and 2 deletions.
7 changes: 5 additions & 2 deletions runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,11 @@ $ funC [global-options] <COMMAND> [command-specific-options] <command-specific-a

## Global options

None are required, but the runtime may support options that start with at least one hyphen.
Global options may take positional arguments (e.g. `--log-level debug`), but the option parsing must be such that `funC <COMMAND>` is unambiguously an invocation of `<COMMAND>` for any `<COMMAND>` that does not start with a hyphen (including commands not specified in this document).
None are required, but the runtime MAY support options that start with at least one hyphen.
Global options MAY take positional arguments (e.g. `--log-level debug`).
Command names MUST not start with hyphens.
The option parsing MUST be such that `funC <COMMAND>` is unambiguously an invocation of `<COMMAND>` (even for commands not specified in this document).
If the runtime is invoked with an unrecognized command, it MUST exit with a nonzero exit code and MAY log a warning to stderr.

## Character encodings

Expand Down

0 comments on commit e9a6625

Please sign in to comment.