Use RFC 2119's keywords (MUST, MAY, ...)

wking · wking · commit 527f3c629a72 · 2015-12-05T11:09:51.000-08:00
This approach has landed in opencontainers/specs [1,2]. You can find the RFC here [3]. [1]: opencontainers/runtime-spec#256 [2]: opencontainers/runtime-spec#260 [3]: http://tools.ietf.org/html/rfc2119 Signed-off-by: W. Trevor King <wking@tremily.us>
diff --git a/runtime.md b/runtime.md
@@ -1,16 +1,16 @@
 # Operations
 
-A conformant runtime should provide an executable (called `funC` in the following examples).
-The template for supported commands is:
+A conformant runtime MUST provide an executable (called `funC` in the following examples).
+That executable MUST support commands with the following template:
 
 ```sh
 $ funC [global-options] <COMMAND> [command-specific-options] <command-specific-arguments>
 ```
 
 ## 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`), 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).
 
 ## Character encodings
 
@@ -23,14 +23,14 @@ For example, POSIX systems define [`LANG` and related environment variables][pos
 
 Print the runtime version and exit.
 
-* *Options* None are required, but the runtime may support options.
+* *Options* None are required, but the runtime MAY support options.
 * *Standard streams*
-  * *stdin:* The runtime may not attempt to read from its stdin.
-  * *stdout:* The runtime must print its name, a space, and its version as the first line to its stdout.
-    The name may contain any Unicode characters except a control codes and newlines.
-    The runtime may print additional lines its stdout, and the format for those lines is not specified in this document.
-  * *stderr:* The runtime may print diagnostic messages to stderr, and the format for those lines is not specified in this document.
-* *Exit code:* The runtime must exit with zero.
+  * *stdin:* The runtime MUST NOT attempt to read from its stdin.
+  * *stdout:* The runtime MUST print its name, a space, and its version as the first line to its stdout.
+    The name MAY contain any Unicode characters, but MUST NOT contain control codes or newlines.
+    The runtime MAY print additional lines its stdout, and the format for those lines is not specified in this document.
+  * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
+* *Exit code:* The runtime MUST exit with zero.
 
 Example:
 ```sh
@@ -50,11 +50,11 @@ Start a container from a bundle directory.
     If not set, the runtime is free to pick any ID that is not already in use.
   * *`--config <PATH>`* Override `config.json` with an alternative path.  The path may not support seeking (e.g. `/dev/fd/3`).
   * *`--runtime <PATH>`* Override `runtime.json` with an alternative path.  The path may not support seeking (e.g. `/dev/fd/3`).
-* *Standard streams:* The runtime must attach its standard streams directly to the application process without inspection.
+* *Standard streams:* The runtime MUST attach its standard streams directly to the application process without inspection.
 * *Environment variables*
   * *`LISTEN_FDS`:* The number of file descriptors passed.
-    For example, `LISTEN_FDS=2` would mean passing 3 and 4 (in addition to the [standard streams][standard-streams]) to support [socket activation][systemd-listen-fds].
-* *Exit code:* The runtime must exit with the application process's exit code.
+    For example, `LISTEN_FDS=2` would mean that the runtime MUST pass file descriptors 3 and 4 to the application process (in addition to the [standard streams][standard-streams]) to support [socket activation][systemd-listen-fds].
+* *Exit code:* The runtime MUST exit with the application process's exit code.
 
 Example:
 ```sh
