Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

layers: describe policy enforcement for foreign layer media type #233

Merged
merged 2 commits into from
Sep 13, 2016

Conversation

stevvooe
Copy link
Contributor

@stevvooe stevvooe commented Sep 1, 2016

Signed-off-by: Stephen J Day [email protected]

Supersedes #216, Requires #169.

@philips
Copy link
Contributor

philips commented Sep 1, 2016

@stephenrwalli Can you take a look at this language? I am still unclear if "MUST NOT distribute" is something we can define usefully in a spec.

I totally get it as a human being with context on copyrights for proprietary software about the usefullness. I just don't know how to codify this. It is like the evil bit RFC: https://www.ietf.org/rfc/rfc3514.txt

Typically, one can download such layers but they should never be uploaded.

Layers that have these restrictions SHOULD be tagged with an alternative mediatype of `application/vnd.oci.image.serialization.rootfs.foreign.tar.gzip`.
[Descriptors][descriptor.md] referencing these layers MAY include `urls` for downloading these layers.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Descriptors][descriptor.md][Descriptors](descriptor.md).

Certain layers, due to legal requirements, may not be regularly distributable.
Typically, one can download such layers but they should never be uploaded.

Layers that have these restrictions SHOULD be tagged with an alternative mediatype of `application/vnd.oci.image.serialization.rootfs.foreign.tar.gzip`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pre-#212 media type pattern?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, good catch!

- `application/vnd.oci.image.config.v1+json`: [Container config JSON](serialization.md)
- `application/vnd.oci.image.layer.tar+gzip`: ["Layer", as a gzipped tar archive](layer.md)
- `application/vnd.oci.image.layer.foreign.tar+gzip`: ["Layer", as a gzipped tar that should never be pushed](layer.md#foreign-layers)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since a foreign layer must not be pushed per the layer spec, might this media type be better defined as "must not be pushed" rather than "should never be pushed"?

Possibly better to redefine "as a non-redistributable gzipped tar archive", or similar.

@jonboulle
Copy link
Contributor

jonboulle commented Sep 6, 2016

-1 on the underspecified use of the "push" verb, as discussed in #216 (comment)

@stevvooe
Copy link
Contributor Author

stevvooe commented Sep 6, 2016

@jonboulle It is sufficient to comment inline on the specific language that needs correcting rather than saying "-1". It is much more constructive, unless you intend to block the PR.

I've replaced the term "push" with the more generic "distribute".

@stephenrwalli
Copy link

@philips I understand your example. It's not necessarily how you would codify it, so much as it gives the certification process the language to revoke a certification based on non-compliance. While it might be difficult to write a test to prove the MUST NOT, if an implementation was demonstrated to distribute such a layer, it clearly doesn't do what the specification says, and would not be able to claim conformance/compliance. Likewise, for a certification process, one can design the process to manual test such a thing or to use the condition to revoke a certification until the implementation complies. Make sense? (Sorry for the tardy reply.)

@wking
Copy link
Contributor

wking commented Sep 7, 2016

On Tue, Sep 06, 2016 at 01:58:50PM -0700, Stephen Walli wrote:

While it might be difficult to write a test to prove the MUST NOT,
if an implementation was demonstrated to distribute such a layer, it
clearly doesn't do what the specification says, and would not be
able to claim conformance/compliance. Likewise, for a certification
process, one can design the process to manual test such a thing or
to use the condition to revoke a certification until the
implementation complies.

“Yeah, automatically testing that would be hard, but we can manually
test it” is a marker for a wishy definition 1. I think the problem
here is that “distributing” is not something that one instance can do
by itself. If it's pushing a blob, someone else must be receiving it.
In some cases (e.g. pushing to a local disk on a single-user system),
that probably doesn't count as “distributing” in a legal sense. In
others (e.g. pushing to a public repo on hub.docker.com) it does.
Where does caching to disk on a multi-user system fall in that
continuum? Are you distributing it by saving to a system-readabale
cache? Or is it only distributing if another user on the system reads
it out of that cache? If that system-readable cache happens to live
under your home directory, are you being robbed (and not distributing)
when the other user reads the file?

I imagine there are consensus opinions on at least some of that
(although I'm not aware of them). I don't think we want to make it
the business of spec implementers and validators to independently
figure out what those opinions are. If there are conditions under
which you would certify (or not) an implementation, I'd like to see
those conditions spelled out in the spec in enough detail for them to
be objectively tested without appealing to “The average person,
applying local community standards, looking at the work in its
entirety” and such. In some cases, that wishyness is unavoidable.
But we need something more solid if we're expecting implementation
software to act consistently based on a ‘foreign’ boolean.

One option would be to have a CAS engine API (e.g. #159) where the
public/private-ness of the engine was part of its initialization.
E.g.:

casEngine, err := NewEngine(ctx, path, public)

Then the engine is non-compliant if you can successfully:

casEngine.Put(ctx, reader, mediaType)

with a foreign mediaType (this is testable by the OCI). And the
engine-initializer is breaking the law if they create a CAS engine
pointing at a public hub.docker.com repo and claiming it is not public
(this is between the CAS engine configurer and the copyright holders
of the pushed content, and not something the OCI has to certify).

@philips
Copy link
Contributor

philips commented Sep 7, 2016

cc @runcom @vbatts ?

@runcom
Copy link
Member

runcom commented Sep 7, 2016

I'm not sure either on this one - is it an hard requirement for this spec to outline the legal matters of foreign layers? I (sorry I may be wrong) don't think so. I think as foreign layers just layers that are downloaded through a list of urls in a descriptor. Do we really need to clarify that those layers can't be distributed? I understand this was born in Docker for this exact legal reason but I don't think the spec should enforce this restriction (not to push) - if people end up pushing the layer it's them breaking any legal terms, I'm not sure what the spec has to do with this. (I believe it's perfectly possible to upload the Windows base layer by taking it and uploading it, implementers (Docker) enforce this, can we just add an implementor note? or add a SHOULD?)

(sorry if any of the above makes no sense...)

@stephenrwalli
Copy link

You make good sense, @runcom. So a way to call attention to such things, that I've seen in the past, is to explicitly call something out as implementation defined. This is basically a warning to spec implementers that are not part of the immediate spec community to pay attention in the space before naively doing something in their implementation. It also allows for the behaviors that already exist in implementations. So in this case, wording becomes: "It is implementation defined whether or not implementations distribute layers tagged with this media type."

@jonboulle
Copy link
Contributor

Such a phrasing would definitely assuage my concerns about the vagueness of "pushing", "distributing", "distributable", etc. (My wariness is largely around combining such terms with the keyword MUST without being very explicit about what they mean.)

@runcom
Copy link
Member

runcom commented Sep 7, 2016

@stephenrwalli that sounds perfect to me if people agree

# Foreign Layers

Certain layers, due to legal requirements, may not be regularly distributable.
Typically, one can download such layers but they should never be uploaded.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@RobDolinMS is going to quibble with this non-SHOULD should (e.g. opencontainers/runtime-spec#536 ;). How about dropping this line, since the idea is covered in the rest of this section?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is an important clarification and frames the stronger language below. I can capitalize the SHOULD or re-phrase it.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On Wed, Sep 07, 2016 at 11:43:09AM -0700, Stephen Day wrote:

@@ -156,3 +156,13 @@ Note that this opaque file will apply to all children, including sub-directori
Implementations SHOULD generate layers using explicit whiteout files, but MUST accept both.

Any given image is likely to be composed of several of these Image Filesystem Changeset tar archives.
+
+# Foreign Layers
+
+Certain layers, due to legal requirements, may not be regularly distributable.
+Typically, one can download such layers but they should never be uploaded.

This is an important clarification and frames the stronger language
below.

What is this line adding beyond the earlier:

Certain layers, due to legal requirements, may not be regularly distributable.

and the planned 1:

It is implementation defined whether or not implementations
distribute layers tagged with this media type.

Can you pin down the information the other lines are missing that
you're trying to convey here?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @wking to drop this line and favor the new one proposed

@wking
Copy link
Contributor

wking commented Sep 7, 2016

On Wed, Sep 07, 2016 at 10:23:08AM -0700, Stephen Walli wrote:

So in this case, wording becomes: "It is implementation defined
whether or not implementations distribute layers tagged with this
media type."

This works for me too.

@wking
Copy link
Contributor

wking commented Sep 7, 2016

On Wed, Sep 07, 2016 at 10:23:08AM -0700, Stephen Walli wrote:

So in this case, wording becomes: "It is implementation defined
whether or not implementations distribute layers tagged with this
media type."

It feels awkard to repeat “implementation”. How about:

It is unspecified whether or not implementations distribute layers
tagged with this media type.

?

@stephenrwalli
Copy link

I believe the suggested text becomes:

Foreign Layers
Layers that have these restrictions SHOULD be tagged with an alternative mediatype of `application/vnd.oci.image.layer.foreign.tar+gzip`.
 [Descriptors](descriptor.md) referencing these layers MAY include `urls` for downloading these layers.
It is implementation defined whether or not implementations upload layers tagged with this media type.

@stephenrwalli
Copy link

@wking I appreciate the awkwardness of language, but I'm using very specific phrasing. "Unspecified" says you can do anything. "Implementation defined" is that bit stronger saying implementations may already do things here and you should pay attention to your choices.

@philips
Copy link
Contributor

philips commented Sep 7, 2016

LGTM

Approved with PullApprove

@wking
Copy link
Contributor

wking commented Sep 7, 2016

On Wed, Sep 07, 2016 at 01:56:09PM -0700, Stephen Walli wrote:

@wking I appreciate the awkwardness of language, but I'm using very
specific phrasing. "Unspecified" says you can do
anything. "Implementation defined" is that bit stronger saying
implementations may already do things here and you should pay
attention to your choices.

Interesting. It looks like C defines those terms [1,2]. If we are
going to split those hairs (and it sounds like a good idea to me), I'd
recommend we put something like that in our spec or reference another
spec to define them for us. Ideally the latter. Is there an
equivalent to RFC 2119 for these terms?

 Page 18 of the PDF, page 11 of the document.

@runcom
Copy link
Member

runcom commented Sep 7, 2016

Are we sticking with the current language?

@philips philips added this to the v1.0.0 milestone Sep 7, 2016
@stevvooe
Copy link
Contributor Author

stevvooe commented Sep 7, 2016

Updated with the new language!


Layers that have these restrictions SHOULD be tagged with an alternative mediatype of `application/vnd.oci.image.layer.foreign.tar+gzip`.
[Descriptors](descriptor.md) referencing these layers MAY include `urls` for downloading these layers.
It is implementation defined whether or not implementations upload layers tagged with this media type.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/upload/distribute?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@runcom I think there were concerns about the meaning of distribute. I'll change it to that if we can re-obtain consensus.

@stephenrwalli CC

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@stevvooe sorry for the noise, I re-read and you're right..

@wking
Copy link
Contributor

wking commented Sep 7, 2016

On Wed, Sep 07, 2016 at 02:40:52PM -0700, Stephen Day wrote:

Updated with the new language!

I still think we want to drop the “should never be uploaded” line 1,
and would like to define “implementation defined” 2. But those can
be addressed in follow-up work if they're too contentious to handle
now, and the rest of fbc6ce4 looks good to me.

@stevvooe
Copy link
Contributor Author

stevvooe commented Sep 9, 2016

@jonboulle I fully agree with the goal of reducing cognitive burden but consistency is also a valid goal. Docker calls this application/vnd.docker.image.rootfs.foreign.diff.tar.gzip and the concepts are isomorphic. Do you think these having different names helps to reduce cognitive burden?

How about we get this merged based on content and concept do another PR where we discuss the name of the media type? Would that suffice?

@wking
Copy link
Contributor

wking commented Sep 9, 2016

On Fri, Sep 09, 2016 at 02:07:49PM -0700, Stephen Day wrote:

Do you think these having different names helps to reduce cognitive
burden?

When the new OCI name is more clear? Yes. If we didn't think so, we
wouldn't have landed #212.

How about we get this merged based on content and concept do another
PR where we discuss the name of the media type? Would that suffice?

I don't see how splitting this discussion out into a new PR will help
resolve it (there's not a lot of other distracting stuff happing in
this one), but if folks feel like that's the case, I'm happy to
discuss foreign → nondistributable in a follow-up PR.

@stevvooe
Copy link
Contributor Author

stevvooe commented Sep 9, 2016

When the new OCI name is more clear? Yes. If we didn't think so, we
wouldn't have landed #212.

#212 actually brings it closer to https://github.com/docker/distribution/blob/master/docs/spec/manifest-v2-2.md#media-types. Before, we had an extra level of indirection in OCI.

I'll say that I am as much of a stickler for naming as anyone, but I'm really just trying to move things forward. I think we have agreement on the concept, but I don't want to get it held up on naming. Let's get the concept in. If we agree on a name change, then we can merge that, as well.

@wking
Copy link
Contributor

wking commented Sep 9, 2016

On Fri, Sep 09, 2016 at 02:39:34PM -0700, Stephen Day wrote:

Let's get the concept in. If we agree on a name change, then we can
merge that, as well.

Fair. I'm just not sure why we don't already have an agreement on
changing the name ;).

@wking
Copy link
Contributor

wking commented Sep 9, 2016

I still have the concerns from 1, which I'm ok ignoring or punting
on, but otherwise e48e595 looks good to me.

@jonboulle
Copy link
Contributor

jonboulle commented Sep 12, 2016

LGTM now, thanks @stevvooe

I do agree with wking's comments in #233 (comment) but we can follow up for that.

Approved with PullApprove

@philips
Copy link
Contributor

philips commented Sep 13, 2016

LGTM

Approved with PullApprove

@philips philips merged commit 2903142 into opencontainers:master Sep 13, 2016
@stevvooe stevvooe deleted the foreign-layer-media-type branch September 13, 2016 19:11
@stevvooe
Copy link
Contributor Author

🎊

@runcom
Copy link
Member

runcom commented Sep 13, 2016

🎉

wking added a commit to wking/image-spec that referenced this pull request Sep 14, 2016
I had been unaware of formal distinctions between these terms until
Stephen Walli called it out [1] in the context of his suggestion to
use "implementation defined" for uploading
application/vnd.oci.image.layer.nondistributable.tar+gzip [2].  I
couldn't find anything as compact as RFC 2119 around this idea, but
linking to a section of the C99 rationale seems reasonable enough.
The PDF I'm linking is "Rationale for International Standard -
Programming Languages - C Revision 5.10 April-2003" and the referenced
content appears in section 3:

  The terms *unspecified behavior*, *undefined behavior*, and
  *implementation-defined behavior* are used to categorize the result
  of writing programs whose properties the Standard does not, or
  cannot, completely describe.  The goal of adopting this
  categorization is to allow a certain variety among implementations
  which permits *quality of implementation* to be an active force in
  the marketplace as well as to allow certain popular extensions,
  without removing the cachet of *conformance to the Standard*.
  Informative Annex J of the Standard catalogs those behaviors which
  fall into one of these three categories.

  *Unspecified behavior* gives the implementor some latitude in
  translating programs.  This latitude does not extend as far as
  failing to translate the program, however, because all possible
  behaviors are "correct" in the sense that they don't cause undefined
  behavior in *any* implementation.

  *Undefined behavior* gives the implementor license not to catch
  certain program errors that are difficult to diagnose.  It also
  identifies areas of possible conforming language extension: the
  implementor may augment the language by providing a definition of
  the officially undefined behavior.

  *Implementation-defined behavior* gives an implementor the freedom
  to choose the appropriate approach, but requires that this choice be
  explained to the user.  Behaviors designated as
  implementation-defined are generally those in which a user could
  make meaningful coding decisions based on the implementation's
  definition.  Implementors should bear in mind this criterion when
  deciding how extensive an implementation definition ought to be.  As
  with unspecified behavior, simply failing to translate the source
  containing the implementation-defined behavior is not an adequate
  response.

The "rationale for the C99 standard" link text seems pretty informal,
but that's what WG14 uses to refer to the document [3].  And I've got
the full title, revision, date, and referenced text in here in case
the link dies and there is any ambiguity about the particular revision
intended ;).

[1]: opencontainers#233 (comment)
[2]: opencontainers#233 (comment)
[3]: http://www.open-std.org/jtc1/sc22/wg14/

Signed-off-by: W. Trevor King <[email protected]>
wking added a commit to wking/image-spec that referenced this pull request Sep 14, 2016
I had been unaware of formal distinctions between these terms until
Stephen Walli called it out [1] in the context of his suggestion to
use "implementation defined" for uploading
application/vnd.oci.image.layer.nondistributable.tar+gzip [2].  I
couldn't find anything as compact as RFC 2119 around this idea, but
linking to a section of the C99 rationale seems reasonable enough.
The PDF I'm linking is "Rationale for International Standard -
Programming Languages - C Revision 5.10 April-2003" and the referenced
content appears in section 3:

  The terms *unspecified behavior*, *undefined behavior*, and
  *implementation-defined behavior* are used to categorize the result
  of writing programs whose properties the Standard does not, or
  cannot, completely describe.  The goal of adopting this
  categorization is to allow a certain variety among implementations
  which permits *quality of implementation* to be an active force in
  the marketplace as well as to allow certain popular extensions,
  without removing the cachet of *conformance to the Standard*.
  Informative Annex J of the Standard catalogs those behaviors which
  fall into one of these three categories.

  *Unspecified behavior* gives the implementor some latitude in
  translating programs.  This latitude does not extend as far as
  failing to translate the program, however, because all possible
  behaviors are "correct" in the sense that they don't cause undefined
  behavior in *any* implementation.

  *Undefined behavior* gives the implementor license not to catch
  certain program errors that are difficult to diagnose.  It also
  identifies areas of possible conforming language extension: the
  implementor may augment the language by providing a definition of
  the officially undefined behavior.

  *Implementation-defined behavior* gives an implementor the freedom
  to choose the appropriate approach, but requires that this choice be
  explained to the user.  Behaviors designated as
  implementation-defined are generally those in which a user could
  make meaningful coding decisions based on the implementation's
  definition.  Implementors should bear in mind this criterion when
  deciding how extensive an implementation definition ought to be.  As
  with unspecified behavior, simply failing to translate the source
  containing the implementation-defined behavior is not an adequate
  response.

The "rationale for the C99 standard" link text seems pretty informal,
but that's what WG14 uses to refer to the document [3].  And I've got
the full title, revision, date, and referenced text in here in case
the link dies and there is any ambiguity about the particular revision
intended ;).

Also update the layer.md instance to use the C99 standard's hyphenated
form.

[1]: opencontainers#233 (comment)
[2]: opencontainers#233 (comment)
[3]: http://www.open-std.org/jtc1/sc22/wg14/

Signed-off-by: W. Trevor King <[email protected]>
wking added a commit to wking/image-spec that referenced this pull request Sep 14, 2016
I had been unaware of formal distinctions between these terms until
Stephen Walli called it out [1] in the context of his suggestion to
use "implementation defined" for uploading
application/vnd.oci.image.layer.nondistributable.tar+gzip [2].  I
couldn't find anything as compact as RFC 2119 around this idea, but
linking to a section of the C99 rationale seems reasonable enough.
The PDF I'm linking is "Rationale for International Standard -
Programming Languages - C Revision 5.10 April-2003" and the referenced
content appears in section 3:

  The terms *unspecified behavior*, *undefined behavior*, and
  *implementation-defined behavior* are used to categorize the result
  of writing programs whose properties the Standard does not, or
  cannot, completely describe.  The goal of adopting this
  categorization is to allow a certain variety among implementations
  which permits *quality of implementation* to be an active force in
  the marketplace as well as to allow certain popular extensions,
  without removing the cachet of *conformance to the Standard*.
  Informative Annex J of the Standard catalogs those behaviors which
  fall into one of these three categories.

  *Unspecified behavior* gives the implementor some latitude in
  translating programs.  This latitude does not extend as far as
  failing to translate the program, however, because all possible
  behaviors are "correct" in the sense that they don't cause undefined
  behavior in *any* implementation.

  *Undefined behavior* gives the implementor license not to catch
  certain program errors that are difficult to diagnose.  It also
  identifies areas of possible conforming language extension: the
  implementor may augment the language by providing a definition of
  the officially undefined behavior.

  *Implementation-defined behavior* gives an implementor the freedom
  to choose the appropriate approach, but requires that this choice be
  explained to the user.  Behaviors designated as
  implementation-defined are generally those in which a user could
  make meaningful coding decisions based on the implementation's
  definition.  Implementors should bear in mind this criterion when
  deciding how extensive an implementation definition ought to be.  As
  with unspecified behavior, simply failing to translate the source
  containing the implementation-defined behavior is not an adequate
  response.

The "rationale for the C99 standard" link text seems pretty informal,
but that's what WG14 uses to refer to the document [3].  And I've got
the full title, revision, date, and referenced text in here in case
the link dies and there is any ambiguity about the particular revision
intended ;).

Also update the layer.md instance to use the C99 standard's hyphenated
form.

[1]: opencontainers#233 (comment)
[2]: opencontainers#233 (comment)
[3]: http://www.open-std.org/jtc1/sc22/wg14/

Signed-off-by: W. Trevor King <[email protected]>
@wking wking mentioned this pull request Sep 18, 2016
wking added a commit to wking/oci-command-line-api that referenced this pull request Feb 10, 2017
I had been unaware of formal distinctions between these terms until
Stephen Walli called it out [1] in the context of his suggestion to
use "implementation defined" for uploading
application/vnd.oci.image.layer.nondistributable.tar+gzip [2].  I
couldn't find anything as compact as RFC 2119 around this idea, but
linking to a section of the C99 rationale seems reasonable enough.
The PDF I'm linking is "Rationale for International Standard -
Programming Languages - C Revision 5.10 April-2003" and the referenced
content appears in section 3:

  The terms *unspecified behavior*, *undefined behavior*, and
  *implementation-defined behavior* are used to categorize the result
  of writing programs whose properties the Standard does not, or
  cannot, completely describe.  The goal of adopting this
  categorization is to allow a certain variety among implementations
  which permits *quality of implementation* to be an active force in
  the marketplace as well as to allow certain popular extensions,
  without removing the cachet of *conformance to the Standard*.
  Informative Annex J of the Standard catalogs those behaviors which
  fall into one of these three categories.

  *Unspecified behavior* gives the implementor some latitude in
  translating programs.  This latitude does not extend as far as
  failing to translate the program, however, because all possible
  behaviors are "correct" in the sense that they don't cause undefined
  behavior in *any* implementation.

  *Undefined behavior* gives the implementor license not to catch
  certain program errors that are difficult to diagnose.  It also
  identifies areas of possible conforming language extension: the
  implementor may augment the language by providing a definition of
  the officially undefined behavior.
  *Implementation-defined behavior* gives an implementor the freedom
  to choose the appropriate approach, but requires that this choice be
  explained to the user.  Behaviors designated as
  implementation-defined are generally those in which a user could
  make meaningful coding decisions based on the implementation's
  definition.  Implementors should bear in mind this criterion when
  deciding how extensive an implementation definition ought to be.  As
  with unspecified behavior, simply failing to translate the source
  containing the implementation-defined behavior is not an adequate
  response.

The "rationale for the C99 standard" link text seems pretty informal,
but that's what WG14 uses to refer to the document [3].  And I've got
the full title, revision, date, and referenced text in here in case
the link dies and there is any ambiguity about the particular revision
intended ;).

[1]: opencontainers/image-spec#233 (comment)
[2]: opencontainers/image-spec#233 (comment)
[3]: http://www.open-std.org/jtc1/sc22/wg14/

Signed-off-by: W. Trevor King <[email protected]>
wking added a commit to wking/oci-command-line-api that referenced this pull request Feb 10, 2017
I had been unaware of formal distinctions between these terms until
Stephen Walli called it out [1] in the context of his suggestion to
use "implementation defined" for uploading
application/vnd.oci.image.layer.nondistributable.tar+gzip [2].  I
couldn't find anything as compact as RFC 2119 around this idea, but
linking to a section of the C99 rationale seems reasonable enough.
The PDF I'm linking is "Rationale for International Standard -
Programming Languages - C Revision 5.10 April-2003" and the referenced
content appears in section 3:

  The terms *unspecified behavior*, *undefined behavior*, and
  *implementation-defined behavior* are used to categorize the result
  of writing programs whose properties the Standard does not, or
  cannot, completely describe.  The goal of adopting this
  categorization is to allow a certain variety among implementations
  which permits *quality of implementation* to be an active force in
  the marketplace as well as to allow certain popular extensions,
  without removing the cachet of *conformance to the Standard*.
  Informative Annex J of the Standard catalogs those behaviors which
  fall into one of these three categories.

  *Unspecified behavior* gives the implementor some latitude in
  translating programs.  This latitude does not extend as far as
  failing to translate the program, however, because all possible
  behaviors are "correct" in the sense that they don't cause undefined
  behavior in *any* implementation.

  *Undefined behavior* gives the implementor license not to catch
  certain program errors that are difficult to diagnose.  It also
  identifies areas of possible conforming language extension: the
  implementor may augment the language by providing a definition of
  the officially undefined behavior.
  *Implementation-defined behavior* gives an implementor the freedom
  to choose the appropriate approach, but requires that this choice be
  explained to the user.  Behaviors designated as
  implementation-defined are generally those in which a user could
  make meaningful coding decisions based on the implementation's
  definition.  Implementors should bear in mind this criterion when
  deciding how extensive an implementation definition ought to be.  As
  with unspecified behavior, simply failing to translate the source
  containing the implementation-defined behavior is not an adequate
  response.

The "rationale for the C99 standard" link text seems pretty informal,
but that's what WG14 uses to refer to the document [3].  And I've got
the full title, revision, date, and referenced text in here in case
the link dies and there is any ambiguity about the particular revision
intended ;).

[1]: opencontainers/image-spec#233 (comment)
[2]: opencontainers/image-spec#233 (comment)
[3]: http://www.open-std.org/jtc1/sc22/wg14/

Signed-off-by: W. Trevor King <[email protected]>
wking added a commit to wking/oci-command-line-api that referenced this pull request Feb 15, 2017
I had been unaware of formal distinctions between these terms until
Stephen Walli called it out [1] in the context of his suggestion to
use "implementation defined" for uploading
application/vnd.oci.image.layer.nondistributable.tar+gzip [2].  I
couldn't find anything as compact as RFC 2119 around this idea, but
linking to a section of the C99 rationale seems reasonable enough.
The PDF I'm linking is "Rationale for International Standard -
Programming Languages - C Revision 5.10 April-2003" and the referenced
content appears in section 3:

  The terms *unspecified behavior*, *undefined behavior*, and
  *implementation-defined behavior* are used to categorize the result
  of writing programs whose properties the Standard does not, or
  cannot, completely describe.  The goal of adopting this
  categorization is to allow a certain variety among implementations
  which permits *quality of implementation* to be an active force in
  the marketplace as well as to allow certain popular extensions,
  without removing the cachet of *conformance to the Standard*.
  Informative Annex J of the Standard catalogs those behaviors which
  fall into one of these three categories.

  *Unspecified behavior* gives the implementor some latitude in
  translating programs.  This latitude does not extend as far as
  failing to translate the program, however, because all possible
  behaviors are "correct" in the sense that they don't cause undefined
  behavior in *any* implementation.

  *Undefined behavior* gives the implementor license not to catch
  certain program errors that are difficult to diagnose.  It also
  identifies areas of possible conforming language extension: the
  implementor may augment the language by providing a definition of
  the officially undefined behavior.
  *Implementation-defined behavior* gives an implementor the freedom
  to choose the appropriate approach, but requires that this choice be
  explained to the user.  Behaviors designated as
  implementation-defined are generally those in which a user could
  make meaningful coding decisions based on the implementation's
  definition.  Implementors should bear in mind this criterion when
  deciding how extensive an implementation definition ought to be.  As
  with unspecified behavior, simply failing to translate the source
  containing the implementation-defined behavior is not an adequate
  response.

The "rationale for the C99 standard" link text seems pretty informal,
but that's what WG14 uses to refer to the document [3].  And I've got
the full title, revision, date, and referenced text in here in case
the link dies and there is any ambiguity about the particular revision
intended ;).

[1]: opencontainers/image-spec#233 (comment)
[2]: opencontainers/image-spec#233 (comment)
[3]: http://www.open-std.org/jtc1/sc22/wg14/

Signed-off-by: W. Trevor King <[email protected]>
dattgoswami9lk5g added a commit to dattgoswami9lk5g/bremlinr that referenced this pull request Jun 6, 2022
I had been unaware of formal distinctions between these terms until
Stephen Walli called it out [1] in the context of his suggestion to
use "implementation defined" for uploading
application/vnd.oci.image.layer.nondistributable.tar+gzip [2].  I
couldn't find anything as compact as RFC 2119 around this idea, but
linking to a section of the C99 rationale seems reasonable enough.
The PDF I'm linking is "Rationale for International Standard -
Programming Languages - C Revision 5.10 April-2003" and the referenced
content appears in section 3:

  The terms *unspecified behavior*, *undefined behavior*, and
  *implementation-defined behavior* are used to categorize the result
  of writing programs whose properties the Standard does not, or
  cannot, completely describe.  The goal of adopting this
  categorization is to allow a certain variety among implementations
  which permits *quality of implementation* to be an active force in
  the marketplace as well as to allow certain popular extensions,
  without removing the cachet of *conformance to the Standard*.
  Informative Annex J of the Standard catalogs those behaviors which
  fall into one of these three categories.

  *Unspecified behavior* gives the implementor some latitude in
  translating programs.  This latitude does not extend as far as
  failing to translate the program, however, because all possible
  behaviors are "correct" in the sense that they don't cause undefined
  behavior in *any* implementation.

  *Undefined behavior* gives the implementor license not to catch
  certain program errors that are difficult to diagnose.  It also
  identifies areas of possible conforming language extension: the
  implementor may augment the language by providing a definition of
  the officially undefined behavior.

  *Implementation-defined behavior* gives an implementor the freedom
  to choose the appropriate approach, but requires that this choice be
  explained to the user.  Behaviors designated as
  implementation-defined are generally those in which a user could
  make meaningful coding decisions based on the implementation's
  definition.  Implementors should bear in mind this criterion when
  deciding how extensive an implementation definition ought to be.  As
  with unspecified behavior, simply failing to translate the source
  containing the implementation-defined behavior is not an adequate
  response.

The "rationale for the C99 standard" link text seems pretty informal,
but that's what WG14 uses to refer to the document [3].  And I've got
the full title, revision, date, and referenced text in here in case
the link dies and there is any ambiguity about the particular revision
intended ;).

Also update the layer.md instance to use the C99 standard's hyphenated
form.

[1]: opencontainers/image-spec#233 (comment)
[2]: opencontainers/image-spec#233 (comment)
[3]: http://www.open-std.org/jtc1/sc22/wg14/

Signed-off-by: W. Trevor King <[email protected]>
7c00d pushed a commit to 7c00d/J1nHyeockKim that referenced this pull request Jun 6, 2022
I had been unaware of formal distinctions between these terms until
Stephen Walli called it out [1] in the context of his suggestion to
use "implementation defined" for uploading
application/vnd.oci.image.layer.nondistributable.tar+gzip [2].  I
couldn't find anything as compact as RFC 2119 around this idea, but
linking to a section of the C99 rationale seems reasonable enough.
The PDF I'm linking is "Rationale for International Standard -
Programming Languages - C Revision 5.10 April-2003" and the referenced
content appears in section 3:

  The terms *unspecified behavior*, *undefined behavior*, and
  *implementation-defined behavior* are used to categorize the result
  of writing programs whose properties the Standard does not, or
  cannot, completely describe.  The goal of adopting this
  categorization is to allow a certain variety among implementations
  which permits *quality of implementation* to be an active force in
  the marketplace as well as to allow certain popular extensions,
  without removing the cachet of *conformance to the Standard*.
  Informative Annex J of the Standard catalogs those behaviors which
  fall into one of these three categories.

  *Unspecified behavior* gives the implementor some latitude in
  translating programs.  This latitude does not extend as far as
  failing to translate the program, however, because all possible
  behaviors are "correct" in the sense that they don't cause undefined
  behavior in *any* implementation.

  *Undefined behavior* gives the implementor license not to catch
  certain program errors that are difficult to diagnose.  It also
  identifies areas of possible conforming language extension: the
  implementor may augment the language by providing a definition of
  the officially undefined behavior.

  *Implementation-defined behavior* gives an implementor the freedom
  to choose the appropriate approach, but requires that this choice be
  explained to the user.  Behaviors designated as
  implementation-defined are generally those in which a user could
  make meaningful coding decisions based on the implementation's
  definition.  Implementors should bear in mind this criterion when
  deciding how extensive an implementation definition ought to be.  As
  with unspecified behavior, simply failing to translate the source
  containing the implementation-defined behavior is not an adequate
  response.

The "rationale for the C99 standard" link text seems pretty informal,
but that's what WG14 uses to refer to the document [3].  And I've got
the full title, revision, date, and referenced text in here in case
the link dies and there is any ambiguity about the particular revision
intended ;).

Also update the layer.md instance to use the C99 standard's hyphenated
form.

[1]: opencontainers/image-spec#233 (comment)
[2]: opencontainers/image-spec#233 (comment)
[3]: http://www.open-std.org/jtc1/sc22/wg14/

Signed-off-by: W. Trevor King <[email protected]>
7c00d added a commit to 7c00d/J1nHyeockKim that referenced this pull request Jun 6, 2022
I had been unaware of formal distinctions between these terms until
Stephen Walli called it out [1] in the context of his suggestion to
use "implementation defined" for uploading
application/vnd.oci.image.layer.nondistributable.tar+gzip [2].  I
couldn't find anything as compact as RFC 2119 around this idea, but
linking to a section of the C99 rationale seems reasonable enough.
The PDF I'm linking is "Rationale for International Standard -
Programming Languages - C Revision 5.10 April-2003" and the referenced
content appears in section 3:

  The terms *unspecified behavior*, *undefined behavior*, and
  *implementation-defined behavior* are used to categorize the result
  of writing programs whose properties the Standard does not, or
  cannot, completely describe.  The goal of adopting this
  categorization is to allow a certain variety among implementations
  which permits *quality of implementation* to be an active force in
  the marketplace as well as to allow certain popular extensions,
  without removing the cachet of *conformance to the Standard*.
  Informative Annex J of the Standard catalogs those behaviors which
  fall into one of these three categories.

  *Unspecified behavior* gives the implementor some latitude in
  translating programs.  This latitude does not extend as far as
  failing to translate the program, however, because all possible
  behaviors are "correct" in the sense that they don't cause undefined
  behavior in *any* implementation.

  *Undefined behavior* gives the implementor license not to catch
  certain program errors that are difficult to diagnose.  It also
  identifies areas of possible conforming language extension: the
  implementor may augment the language by providing a definition of
  the officially undefined behavior.

  *Implementation-defined behavior* gives an implementor the freedom
  to choose the appropriate approach, but requires that this choice be
  explained to the user.  Behaviors designated as
  implementation-defined are generally those in which a user could
  make meaningful coding decisions based on the implementation's
  definition.  Implementors should bear in mind this criterion when
  deciding how extensive an implementation definition ought to be.  As
  with unspecified behavior, simply failing to translate the source
  containing the implementation-defined behavior is not an adequate
  response.

The "rationale for the C99 standard" link text seems pretty informal,
but that's what WG14 uses to refer to the document [3].  And I've got
the full title, revision, date, and referenced text in here in case
the link dies and there is any ambiguity about the particular revision
intended ;).

Also update the layer.md instance to use the C99 standard's hyphenated
form.

[1]: opencontainers/image-spec#233 (comment)
[2]: opencontainers/image-spec#233 (comment)
[3]: http://www.open-std.org/jtc1/sc22/wg14/

Signed-off-by: W. Trevor King <[email protected]>
laventuraw added a commit to laventuraw/Kihara-tony0 that referenced this pull request Jun 6, 2022
I had been unaware of formal distinctions between these terms until
Stephen Walli called it out [1] in the context of his suggestion to
use "implementation defined" for uploading
application/vnd.oci.image.layer.nondistributable.tar+gzip [2].  I
couldn't find anything as compact as RFC 2119 around this idea, but
linking to a section of the C99 rationale seems reasonable enough.
The PDF I'm linking is "Rationale for International Standard -
Programming Languages - C Revision 5.10 April-2003" and the referenced
content appears in section 3:

  The terms *unspecified behavior*, *undefined behavior*, and
  *implementation-defined behavior* are used to categorize the result
  of writing programs whose properties the Standard does not, or
  cannot, completely describe.  The goal of adopting this
  categorization is to allow a certain variety among implementations
  which permits *quality of implementation* to be an active force in
  the marketplace as well as to allow certain popular extensions,
  without removing the cachet of *conformance to the Standard*.
  Informative Annex J of the Standard catalogs those behaviors which
  fall into one of these three categories.

  *Unspecified behavior* gives the implementor some latitude in
  translating programs.  This latitude does not extend as far as
  failing to translate the program, however, because all possible
  behaviors are "correct" in the sense that they don't cause undefined
  behavior in *any* implementation.

  *Undefined behavior* gives the implementor license not to catch
  certain program errors that are difficult to diagnose.  It also
  identifies areas of possible conforming language extension: the
  implementor may augment the language by providing a definition of
  the officially undefined behavior.

  *Implementation-defined behavior* gives an implementor the freedom
  to choose the appropriate approach, but requires that this choice be
  explained to the user.  Behaviors designated as
  implementation-defined are generally those in which a user could
  make meaningful coding decisions based on the implementation's
  definition.  Implementors should bear in mind this criterion when
  deciding how extensive an implementation definition ought to be.  As
  with unspecified behavior, simply failing to translate the source
  containing the implementation-defined behavior is not an adequate
  response.

The "rationale for the C99 standard" link text seems pretty informal,
but that's what WG14 uses to refer to the document [3].  And I've got
the full title, revision, date, and referenced text in here in case
the link dies and there is any ambiguity about the particular revision
intended ;).

Also update the layer.md instance to use the C99 standard's hyphenated
form.

[1]: opencontainers/image-spec#233 (comment)
[2]: opencontainers/image-spec#233 (comment)
[3]: http://www.open-std.org/jtc1/sc22/wg14/

Signed-off-by: W. Trevor King <[email protected]>
tomalopbsr0tt added a commit to tomalopbsr0tt/fabiojosej that referenced this pull request Oct 6, 2022
I had been unaware of formal distinctions between these terms until
Stephen Walli called it out [1] in the context of his suggestion to
use "implementation defined" for uploading
application/vnd.oci.image.layer.nondistributable.tar+gzip [2].  I
couldn't find anything as compact as RFC 2119 around this idea, but
linking to a section of the C99 rationale seems reasonable enough.
The PDF I'm linking is "Rationale for International Standard -
Programming Languages - C Revision 5.10 April-2003" and the referenced
content appears in section 3:

  The terms *unspecified behavior*, *undefined behavior*, and
  *implementation-defined behavior* are used to categorize the result
  of writing programs whose properties the Standard does not, or
  cannot, completely describe.  The goal of adopting this
  categorization is to allow a certain variety among implementations
  which permits *quality of implementation* to be an active force in
  the marketplace as well as to allow certain popular extensions,
  without removing the cachet of *conformance to the Standard*.
  Informative Annex J of the Standard catalogs those behaviors which
  fall into one of these three categories.

  *Unspecified behavior* gives the implementor some latitude in
  translating programs.  This latitude does not extend as far as
  failing to translate the program, however, because all possible
  behaviors are "correct" in the sense that they don't cause undefined
  behavior in *any* implementation.

  *Undefined behavior* gives the implementor license not to catch
  certain program errors that are difficult to diagnose.  It also
  identifies areas of possible conforming language extension: the
  implementor may augment the language by providing a definition of
  the officially undefined behavior.

  *Implementation-defined behavior* gives an implementor the freedom
  to choose the appropriate approach, but requires that this choice be
  explained to the user.  Behaviors designated as
  implementation-defined are generally those in which a user could
  make meaningful coding decisions based on the implementation's
  definition.  Implementors should bear in mind this criterion when
  deciding how extensive an implementation definition ought to be.  As
  with unspecified behavior, simply failing to translate the source
  containing the implementation-defined behavior is not an adequate
  response.

The "rationale for the C99 standard" link text seems pretty informal,
but that's what WG14 uses to refer to the document [3].  And I've got
the full title, revision, date, and referenced text in here in case
the link dies and there is any ambiguity about the particular revision
intended ;).

Also update the layer.md instance to use the C99 standard's hyphenated
form.

[1]: opencontainers/image-spec#233 (comment)
[2]: opencontainers/image-spec#233 (comment)
[3]: http://www.open-std.org/jtc1/sc22/wg14/

Signed-off-by: W. Trevor King <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants