Skip to content

Commit

Permalink
runtime: Semantically version this specification
Browse files Browse the repository at this point in the history
The command-line interface is largely orthogonal to the config format,
and config authors and runtime callers may be entirely different sets
of people.  Zhang Wei called for more explicit versioning for the CLI
[1].

Wedging multiple, independently versioned entities into a single
repository can be awkward, but earlier proposals to put the CLI in its
own repository [2] were unsuccessful because compliance testing
requires both a CLI and a config specification [3].  I don't think
that's a solid reason [4], but discussion along that line stalled out,
before being revived in today's meeting.  Unfortunately, now this CLI
spec is destined for runtime-tools [5], so we may still have multiple,
independently versioned entities in a single repository.  Wherever
this lands up, it's useful for this CLI spec to be clear about it's
own versioning.

[1]: opencontainers/runtime-spec#513 (comment)
[2]: opencontainers/runtime-spec#513 (comment)
[3]: opencontainers/runtime-spec#513 (comment)
[4]: opencontainers/runtime-spec#513 (comment)
[5]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2017/opencontainers.2017-02-08-22.00.log.html#l-125

Signed-off-by: W. Trevor King <wking@tremily.us>
  • Loading branch information
wking committed Feb 8, 2017
1 parent e71f7aa commit 477a476
Showing 1 changed file with 13 additions and 1 deletion.
14 changes: 13 additions & 1 deletion runtime.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,16 @@
# OCI Runtime Command Line Interface

A conformant runtime MUST provide an executable (called `funC` in the following examples).
This section defines the OCI Runtime Command Line Interface version 1.0.0.

## Versioning

The command line interface is versioned with [SemVer v2.0.0][semver].
The command line interface version is independent of the OCI Runtime Specification as a whole (which is tied to the [configuration format][runtime-spec-version].
For example, if a caller is compliant with version 1.1 of the command line interface, they are compatible with all runtimes that support any 1.1 or later release of the command line interface, but are not compatible with a runtime that supports 1.0 and not 1.1.

## Global usage

The runtime MUST provide an executable (called `funC` in the following examples).
That executable MUST support commands with the following template:

```sh
Expand Down Expand Up @@ -105,6 +115,8 @@ $ echo $?
[posix-encoding]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap06.html#tag_06_02
[posix-lang]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_02
[posix-locale-encoding]: http://www.unicode.org/reports/tr35/#Bundle_vs_Item_Lookup
[semver]: http://semver.org/spec/v2.0.0.html
[standard-streams]: https://github.com/opencontainers/specs/blob/v0.1.1/runtime-linux.md#file-descriptors
[systemd-listen-fds]: http://www.freedesktop.org/software/systemd/man/sd_listen_fds.html
[runtime-spec-version]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/config.md#specification-version
[UTF-8]: http://www.unicode.org/versions/Unicode8.0.0/ch03.pdf

0 comments on commit 477a476

Please sign in to comment.