Skip to content

Commit

Permalink
Use RFC 2119's keywords (MUST, MAY, ...)
Browse files Browse the repository at this point in the history
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 <[email protected]>
  • Loading branch information
wking committed Dec 5, 2015
1 parent 10d725a commit 527f3c6
Showing 1 changed file with 14 additions and 14 deletions.
28 changes: 14 additions & 14 deletions runtime.md
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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
Expand All @@ -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
Expand Down

9 comments on commit 527f3c6

@mikebrow
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed. Looks good to me.

@wking
Copy link
Owner Author

@wking wking commented on 527f3c6 Dec 7, 2015 via email

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mikebrow
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MAY means OPTIONAL. So in the first example you are saying additional options are in fact optional. In the second example you are saying those semantics are optional for the log level option are optional semantics. Lower case may holds less weight.

@wking
Copy link
Owner Author

@wking wking commented on 527f3c6 Dec 7, 2015 via email

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mikebrow
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They were not saying that MAY is a generic extension mechanism. They are saying it means truly optional for the item. For extensions and whether or not the global options MUST NOT fail fast and MUST instead allow for plugins/hooks/extensions etc. to process said unknown global options... Well you just need to make that statement if that's what you want :-)

@mikebrow
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IOW the language in rfc2119 around MAY include an item means the item is optional. Item is one of those legal terms. It's used for substitution. You replace the word item with your thing that is made optional by the use of the word MAY.

@wking
Copy link
Owner Author

@wking wking commented on 527f3c6 Dec 7, 2015 via email

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@wking
Copy link
Owner Author

@wking wking commented on 527f3c6 Dec 8, 2015 via email

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mikebrow
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes it makes sense. Note: The might language is simply listing options. It's not saying those are the only options or that one has be be chosen to be compliant. Thus.... the use of the term MAY is just to say it's truly optional to have a reply to field. It is not necessary to have a reply to field.

Please sign in to comment.