[README] Add a should

[coolljt0725]

Signed-off-by: Lei Jitang [email protected]

To support the UX describe above, OCI Image Format should contains sufficient information.

[wking]

I don't think we need this. The “sufficient information” line guides
the development of this spec, it's not a requirement for either
implementations or image authors. And see
opencontainers/runtime-spec#536 and some discussion around 1 about
avoiding “should” in favor of either other words or the normative
“SHOULD”. In this case, I think the text is already appropriately
using the other-words approach.

[coolljt0725]

@wking I'm not sure if this is need or not
There is a description above this sentence says that:

This entire workflow supports the UX that users have come to expect from container engines like Docker and rkt: primarily, the ability to run an image with no additional arguments:

docker run example.com/org/app:v1.0.0
rkt run example.com/org/app,version=v1.0.0

to support this UX, the OCI Image should contains sufficient information. If Image doesn't contain some information such as entrypoint cmd, the UX describe above is impossible. The image must contains sufficient information to support this UX.

[wking]

On Sun, Sep 18, 2016 at 06:29:40PM -0700, Lei Jitang wrote:

… to support this UX, the OCI Image should contains sufficient
information. If Image doesn't contain some information such as
entrypoint cmd, the UX describe above is impossible. The image
must contains sufficient information to support this UX.

I agree in prinicple that this is a worthy goal. However, SHOULD
means it's a normative recommendation, and “contains sufficient
information…” is not specific enough to be testable. Requirements on
the content should live at the property level, e.g. 1 where we
explicitly allow entrypoint to be null (more on why in #152).

[coolljt0725]

@wking

Requirements on
the content should live at the property level, e.g. [1] where we
explicitly allow entrypoint to be null (more on why in #152).

I once open a issue for this #218 , and @philips answered my question

Just because we should support that UX does not mean that every image MUST support that UX. For example there are Debian base images that don't really make sense to run.

From what I understanding, not all the image MUST support that UX, but if the image support that UX, it should contains sufficient information.

[wking]

On Sun, Sep 18, 2016 at 11:35:01PM -0700, Lei Jitang wrote:

From what I understanding, not all the image MUST support that UX,
but if the image support that UX, it should contains sufficient
information.

If the image wants to support that UX, it MUST contain entrypoint,
right? But still, this is something you'll want to point out where
we define the entrypoint property. Making a normative statement here
means you'd have to define “contains sufficient information…”
somewhere, and I don't see that defined anywhere at the moment.
There's just the wishy “e.g. command, …”, and that doesn't sound like
a normative definition.

On the other hand, a bit of handwaving around an informative hint
(“here's a UX to think about when deciding which properties to set”)
is fine. We just don't want to use the normative “SHOULD” for such a
hint, and I'd rather avoid the informative “should” to avoid confusion
with the normative “SHOULD” (links to previous “avoid ‘should’”
discussion in 1).

[coolljt0725]

@wking sufficient information is hard to define, I think different image has different sufficient information, the image provider knows what the sufficient information is to support such UX.

On the other hand, a bit of handwaving around an informative hint
(“here's a UX to think about when deciding which properties to set”)
is fine. We just don't want to use the normative “SHOULD” for such a
hint, and I'd rather avoid the informative “should” to avoid confusion
with the normative “SHOULD” (links to previous “avoid ‘should’”
discussion in [1]).

If we want drop the should, I think we could re-write the sentence.

[wking]

On Mon, Sep 19, 2016 at 07:03:24PM -0700, Lei Jitang wrote:

@wking sufficient information is hard to define…

Agreed, which is why I want to stay away from “SHOULD”.

If we want drop the should, I think we could re-write the
sentence.

I think the sentance was fine how it was, but am open to other
rephrasings. Maybe something like:

The OCI Image Format supports this UX by defining configuration
properties sufficient to launch the application on the target
platform (e.g. command, arguments, environment variables, etc.).

which is more clearly a guiding principle for developing the spec and
not a requirement placed on image authors (with those image-author
requirements living where the properties are defined).

[vbatts]

@coolljt0725 this "should" seems to be an enforcement on the spec itself, not something enforcing on implementers. Perhaps this is not needed?

[coolljt0725]

@vbatts Yes, it's on the spec itself