-
Notifications
You must be signed in to change notification settings - Fork 652
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
layers: describe policy enforcement for foreign layer media type #233
Conversation
@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. |
There was a problem hiding this comment.
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)
.
e7aa01a
to
6c5b891
Compare
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`. |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, good catch!
6c5b891
to
9b3d777
Compare
- `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) |
There was a problem hiding this comment.
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.
-1 on the underspecified use of the "push" verb, as discussed in #216 (comment) |
9b3d777
to
4b60850
Compare
@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". |
@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.) |
On Tue, Sep 06, 2016 at 01:58:50PM -0700, Stephen Walli wrote:
“Yeah, automatically testing that would be hard, but we can manually I imagine there are consensus opinions on at least some of that One option would be to have a CAS engine API (e.g. #159) where the 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 |
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...) |
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." |
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.) |
@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. |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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
On Wed, Sep 07, 2016 at 10:23:08AM -0700, Stephen Walli wrote:
This works for me too. |
On Wed, Sep 07, 2016 at 10:23:08AM -0700, Stephen Walli wrote:
It feels awkard to repeat “implementation”. How about: It is unspecified whether or not implementations distribute layers ? |
I believe the suggested text becomes:
|
@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. |
On Wed, Sep 07, 2016 at 01:56:09PM -0700, Stephen Walli wrote:
Interesting. It looks like C defines those terms [1,2]. If we are
|
Are we sticking with the current language? |
4b60850
to
fbc6ce4
Compare
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
s/upload/distribute?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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..
On Wed, Sep 07, 2016 at 02:40:52PM -0700, Stephen Day wrote:
I still think we want to drop the “should never be uploaded” line 1, |
Signed-off-by: Stephen J Day <[email protected]>
ba1ac91
to
8a0c75c
Compare
@jonboulle I fully agree with the goal of reducing cognitive burden but consistency is also a valid goal. Docker calls this 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? |
On Fri, Sep 09, 2016 at 02:07:49PM -0700, Stephen Day wrote:
When the new OCI name is more clear? Yes. If we didn't think so, we
I don't see how splitting this discussion out into a new PR will help |
#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. |
On Fri, Sep 09, 2016 at 02:39:34PM -0700, Stephen Day wrote:
Fair. I'm just not sure why we don't already have an agreement on |
Signed-off-by: Stephen J Day <[email protected]>
LGTM now, thanks @stevvooe I do agree with wking's comments in #233 (comment) but we can follow up for that. |
🎊 |
🎉 |
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]>
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]>
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]>
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]>
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]>
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]>
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]>
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]>
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]>
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]>
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]>
Signed-off-by: Stephen J Day [email protected]
Supersedes #216, Requires #169.