Clarity for commands vs global options

mikebrow · mikebrow · commit 2b084a3539f9 · 2015-12-08T00:10:24.000-06:00
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>
diff --git a/runtime.md b/runtime.md
@@ -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
 
