From c94e7c0ace99c8ef7009b9c741180e8f4cb6ca42 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Tue, 26 Jul 2016 14:22:16 -0700 Subject: [PATCH] config: Clarify ociVersion covering the configuration <-> runtime API There are other APIs described in this specification (e.g. the state JSON format, and the in-flight command-line API [1]), but this string covers the configuration file and referenced objects (e.g. the filesystem at root.path). As additional, backwards compatible features are added to the spec (leading to 1.1, 1.2, etc. releases) and supported by runtimes, those runtimes will *still* stupport 1.0 configs. Once a 2.0 spec is cut, runtimes that only support 2.0 (and nothing in the 1.0 line) will no longer support the 1.0 config. My preferred approach here would be to use JSON-LD [2,3,4] to explicitly document the intended semantics for each field, which would allow us to drop the config-wide version and version each field independently. That would mean a breaking change on a particular field would only break compatibility for folks who were using that field. Unfortunately, I haven't had much luck pushing the consensus in that direction. This commit does not add wording about how the runtime and other consumers should handle an incompatible version. We can address that once the command-line API lands. [1]: https://github.com/opencontainers/runtime-spec/pull/513 [2]: https://github.com/opencontainers/runtime-spec/pull/371#issuecomment-209684002 [3]: https://github.com/opencontainers/image-spec/pull/111#discussion_r65619280 [4]: https://github.com/opencontainers/runtime-spec/pull/510#discussion_r68513241 Signed-off-by: W. Trevor King --- config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config.md b/config.md index 0a21d654d..0228be213 100644 --- a/config.md +++ b/config.md @@ -12,7 +12,7 @@ Below is a detailed description of each field defined in the configuration forma * **`ociVersion`** (string, required) MUST be in [SemVer v2.0.0](http://semver.org/spec/v2.0.0.html) format and specifies the version of the Open Container Runtime Specification with which the bundle complies. The Open Container Runtime Specification follows semantic versioning and retains forward and backward compatibility within major versions. -For example, if an implementation is compliant with version 1.0.1 of the spec, it is compatible with the complete 1.x series. +For example, if a configuration is compliant with version 1.1 of this specification, it is compatible with all runtimes that support any 1.1 or later release of this specification, but is not compatible with a runtime that supports 1.0 and not 1.1. ### Example