Add language for compliance requirements around platforms #527

mrunalp · 2016-08-10T19:22:07Z

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

wking · 2016-08-10T19:36:04Z

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 · 2016-08-10T20:40:44Z

@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 · 2016-08-10T20:56:50Z

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 · 2016-08-10T21:09:30Z

I like @wking 's wording.

philips · 2016-08-10T21:12:04Z

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

hqhq · 2016-08-11T01:58:52Z

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

mrunalp · 2016-08-16T18:24:02Z

Updated.

wking · 2016-08-16T18:33:29Z

README.md

@@ -25,7 +25,10 @@ Table of Contents
 In the specifications in the above table of contents, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119) (Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997).

 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".
+An implementation that satisfies all the MUST or REQUIRED and all the SHOULD requirements for its protocols is said to be "unconditionally compliant" on one or more CPU architectures.


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”).

Sounds good. Thanks!

…ctures Signed-off-by: Mrunal Patel <mrunalp@gmail.com>

mrunalp · 2016-08-17T17:45:35Z

Pushed update.

wking · 2016-08-17T17:54:26Z

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.

…pliance language Signed-off-by: Mrunal Patel <mrunalp@gmail.com>

mrunalp · 2016-08-17T18:02:01Z

@opencontainers/runtime-spec-maintainers PTAL

wking · 2016-08-17T18:18:35Z

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 · 2016-08-19T03:14:53Z

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 · 2016-08-19T16:46:01Z

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 · 2016-08-22T20:59:25Z

README.md

+
+Protocols defined by this specification are:
+* Linux containers: [runtime.md](runtime.md), [config.md](config.md), [config-linux.md](config-linux.md), and [runtime-linux.md](runtime-linux.md).
+* Solaris containers: [runtime.md](runtime.md), [config.md](config.md), and [config-solaris.md](config-solaris.md).


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 · 2016-08-26T15:12:08Z

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 · 2016-08-26T15:25:15Z

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 · 2016-08-26T15:45:33Z

@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 · 2016-08-26T15:53:28Z

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 · 2016-08-29T14:29:06Z

LGTM

So that the semantics are clear. The platform/protocol disconnect is unfortunate. "Protocol" was chosen in de3f1af (Remove language around Solaris being optional as it is covered in compliance language, 2016-08-17, opencontainers#527) because we may have compliance subsets that aren't linked to platforms [2]. I'd be open to renaming the JSON tag from platform:"..." -> protocol:"...", but that's probably more change than it's worth. [1]: opencontainers#527 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

So that the semantics of the tags are clear. The platform/protocol disconnect is unfortunate. "Protocol" was chosen in de3f1af (Remove language around Solaris being optional as it is covered in compliance language, 2016-08-17, opencontainers#527) because we may have compliance subsets that aren't linked to platforms [1]. I'd be open to renaming the JSON tag from platform:"..." -> protocol:"...", but that's probably more change than it's worth. The approach taken in this commit, on the other hand, renames "protocol" to "platform". I think that unnecessarily limits (or sets up confusing semantics for) the platform/protocol values you can use, but two maintainers both prefer "platform" [2,3]. [1]: opencontainers#527 (comment) [2]: opencontainers#570 (comment) [3]: opencontainers#570 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

mrunalp force-pushed the plat_comp branch from 4f09875 to 1c8413b Compare August 16, 2016 18:23

wking reviewed Aug 16, 2016
View reviewed changes

Add language for compliance requirements around platforms and archite…

6a5b144

…ctures Signed-off-by: Mrunal Patel <mrunalp@gmail.com>

mrunalp force-pushed the plat_comp branch from 1c8413b to 6a5b144 Compare August 17, 2016 17:45

Remove language around Solaris being optional as it is covered in com…

de3f1af

…pliance language Signed-off-by: Mrunal Patel <mrunalp@gmail.com>

wking mentioned this pull request Aug 17, 2016

*: Remove hooks #483

Closed

wking mentioned this pull request Aug 22, 2016

[Style] Remove "should" not related to conformance #536

Closed

wking reviewed Aug 22, 2016
View reviewed changes

wking mentioned this pull request Aug 24, 2016

[ReadMe] Adds boilerplate MUST, MAY, etc. language opencontainers/image-spec#207

Merged

vbatts merged commit a3d7507 into opencontainers:master Aug 29, 2016

wking mentioned this pull request Aug 29, 2016

[ReadMe] Just one level/tier of compliance #543

Closed

This was referenced Sep 1, 2016

[ReadMe] Just one level/tier of compliance (rebase) #553

Merged

Add Runtime CLI Spec #513

Closed

wking mentioned this pull request Sep 15, 2016

config: Link platform:"…" JSON tags with ~~protocol~~ platform slugs #570

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add language for compliance requirements around platforms #527

Add language for compliance requirements around platforms #527

mrunalp commented Aug 10, 2016

wking commented Aug 10, 2016

mrunalp commented Aug 10, 2016

wking commented Aug 10, 2016

mikebrow commented Aug 10, 2016 •

edited

Loading

philips commented Aug 10, 2016

hqhq commented Aug 11, 2016

mrunalp commented Aug 16, 2016

wking Aug 16, 2016

mrunalp Aug 17, 2016

mrunalp commented Aug 17, 2016

wking commented Aug 17, 2016

mrunalp commented Aug 17, 2016

wking commented Aug 17, 2016 via email

hqhq commented Aug 19, 2016 •

edited by caniszczyk

Loading

wking commented Aug 19, 2016

wking Aug 22, 2016

hqhq commented Aug 26, 2016

wking commented Aug 26, 2016

hqhq commented Aug 26, 2016

wking commented Aug 26, 2016

vbatts commented Aug 29, 2016 •

edited by caniszczyk

Loading

Add language for compliance requirements around platforms #527

Add language for compliance requirements around platforms #527

Conversation

mrunalp commented Aug 10, 2016

wking commented Aug 10, 2016

mrunalp commented Aug 10, 2016

wking commented Aug 10, 2016

mikebrow commented Aug 10, 2016 • edited Loading

philips commented Aug 10, 2016

hqhq commented Aug 11, 2016

mrunalp commented Aug 16, 2016

wking Aug 16, 2016

Choose a reason for hiding this comment

mrunalp Aug 17, 2016

Choose a reason for hiding this comment

mrunalp commented Aug 17, 2016

wking commented Aug 17, 2016

mrunalp commented Aug 17, 2016

wking commented Aug 17, 2016 via email

hqhq commented Aug 19, 2016 • edited by caniszczyk Loading

wking commented Aug 19, 2016

wking Aug 22, 2016

Choose a reason for hiding this comment

hqhq commented Aug 26, 2016

wking commented Aug 26, 2016

hqhq commented Aug 26, 2016

wking commented Aug 26, 2016

vbatts commented Aug 29, 2016 • edited by caniszczyk Loading

mikebrow commented Aug 10, 2016 •

edited

Loading

hqhq commented Aug 19, 2016 •

edited by caniszczyk

Loading

vbatts commented Aug 29, 2016 •

edited by caniszczyk

Loading