Add language for compliance requirements around platforms

[mrunalp]

Signed-off-by: Mrunal Patel mrunalp@gmail.com

[wking]

I'd rather not use both “one of the platforms” and “for the protocols
it implements”. If we want to split this spec into “protocols” we
should stick to the protocols language with the new addition. If we
want to switch to “platforms” language, we should update the existing
compliance language to use “platforms”.

The “platforms” phrasing is nice and specific for the current spec,
but discussion in #513 included “what if we support ‘at least one of
the following APIs’?” 1, so we may want to stick with the
less-specific “protocols” phrasing to cover both platforms and APIs.
In that case I think it makes sense to make the mapping between
protocols and MUST/SHOULD/… requirements clear. For example:

An implementation is not compliant if it fails to satisfy one or
more of the MUST or REQUIRED requirements for the protocols it
implements. An implementation that satisfies all the MUST or
REQUIRED and all the SHOULD requirements for its protocols is said
to be "unconditionally compliant". Protocols defined by this spec
are:

• Linux containers: runtime.md, config.md, config-linux.md, and
  runtime-linux.md.
• Solaris containers: runtime.md, config.md, and config-solaris.md.

And once we land an API spec, it would look something like:

• Linux containers: runtime.md, config.md, config-linux.md,
  runtime-linux.md, and an API.

• Solaris containers: runtime.md, config.md and config-solaris.md,
  and an API.

  APIs include at least one of:

• The command line API

[mrunalp]

@wking I like your wording but we want to avoid repeating the line for each platform if we can. The only thing that will be different is config-platform.md.

[wking]

On Wed, Aug 10, 2016 at 01:40:45PM -0700, Mrunal Patel wrote:

The only thing that will be different is config-platform.md.

That's not true now, although it would be if you can roll
runtime-linux.md into other places. #513 moves the standard-streams
stuff into the command line API and you could move the dev links into
config-linux.md. If we do get a consistent pattern for which files
are part of which “protocols”, I'm fine just explaining the pattern
instead of listing them all out.

[mikebrow]

I like @wking 's wording.

[philips]

As discussed on the call @mrunalp please add language around "system architectures (ARM, x86-64, etc)" as well as OSes.

[hqhq]

OSes are platforms, by architecture, we usually mean x86_64, ARM etc.. I think we need language about architectures.

[mrunalp]

Updated.

[wking]

As it stands, your CPU qualification only covers “unconditionally compliant”, and we want to qualify “compliant” as well. How about:

An implementation is not compliant for a given CPU architecture if it fails to satisfy one or more of the MUST or REQUIRED requirements for the protocols it implements.
An implementation is compliant for a given CPU architecture if it satisfies all the MUST and REQUIRED requirements for the protocols it implements.
An implementation that satisfies all the MUST or REQUIRED and all the SHOULD requirements for its protocols on a given CPU architecture is said to be "unconditionally compliant" with those protocols and architectures.

which also covers “compliant” explicitly (it was previously implied to be “all cases that aren't explicitly non-compliant”).

[mrunalp]

Sounds good. Thanks!

[mrunalp]

Pushed update.

[wking]

On Wed, Aug 17, 2016 at 10:45:36AM -0700, Mrunal Patel wrote:

Pushed update.

6a5b144 looks good to me.

We probably want to remove wiggles like “The Solaris specification is
entirely optional” 1 now that we have this centralized definition of
what requirements belong to which protocols. I'm fine discussing that
as part of this PR if folks want, or punting it to follow up work.

[mrunalp]

@opencontainers/runtime-spec-maintainers PTAL

[wking]

de3f1af looks good to me too. I'm not aware of anything else that should change to match this new compliance language, but we can find and fix other issues (if any) later on.

[hqhq]

LGTM, I thought we might need some CPU architecture specific fields in spec, but we need to figure out what fields and if they exist.

[wking]

On Thu, Aug 18, 2016 at 08:14:54PM -0700, Qiang Huang wrote:

LGTM, I thought we might need some CPU architecture specific fields
in spec, but we need to figure out what fields and if they exist.

The current PR has “for a given CPU architecture” and similar language
and the spec has a platform.arch field. What more are you looking
for? Are you talking about #39 and #69?

[wking]

Thinking over the tangentially-related #536, we probably want to include bundle.md and glossary.md in both lists.

I think including glossary.md is unfortunate; perhaps we can revisit the decision to put the UTF-8 requirement for configuration JSON there?

[hqhq]

The current PR has “for a given CPU architecture” and similar language
and the spec has a platform.arch field. What more are you looking
for? Are you talking about #39 and #69?

Yeah, something like that, and I think the problem described in #39 is not resolved yet, GOARCH from golang is not sufficient for all architectures, maybe we should reopen it and discuss more.

[wking]

On Fri, Aug 26, 2016 at 08:12:09AM -0700, Qiang Huang wrote:

… I think the problem described in #39 is not resolved yet, GOARCH
from golang is not sufficient for all architectures…

#441 brought over some language from opencontainers/image-spec#60 that
says “If you need something that's not in GOARCH, please let us know”.
I think that allows us to patch holes in GOARCH as they arise.

[hqhq]

@wking Maybe for architecture itself, GOARCH would be sufficient, but we might need some information like byte order, variant, abi etc.. which might be considered out of architecture name, so argue with GOARCH may not be a wise move.

[wking]

On Fri, Aug 26, 2016 at 08:45:34AM -0700, Qiang Huang wrote:

… so argue with GOARCH may not be a wise move.

Maybe not, I don't know. But I still think the “for a given CPU
architecture” covers the current non-OS portion of ‘platform’.
If/when we land language for platform.byte-order (or whatever), we can
amend the architecture-ish scoping here.

[vbatts]

LGTM