README: Define "unspecified", "undefined", and "implementation-defined" #311
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
wking
force-pushed
the
unspecified-undefined-and-implemenation-defined
branch
from
028c05c to
01687e9
Compare
| @@ -9,6 +9,8 @@ The combination of the image manifest, image configuration, and one or more file | |||
|
|
|||
| The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119) (Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997). | |||
|
|
|||
| The keywords "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the [rationale for the C99 standard][unspecified]. | |||
There was a problem hiding this comment.
"unspecified" is an awkward name for a link (especially a reference one because at first blush it looks like a placeholder) - can you call this c99rationale or similar?
There was a problem hiding this comment.
On Wed, Sep 14, 2016 at 02:58:04AM -0700, Jonathan Boulle wrote:
+The keywords "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the [rationale for the C99 standard][unspecified].
"unspecified" is an awkward name for a link (especially a reference
one because at first blush it looks like a placeholder) - can you
call this c99rationale or similar?
In case we ever link to another part of the c99 rationale, I've gone
with c99-unspecified in 01687e9 → 2d49333.
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 <wking@tremily.us>
wking
force-pushed
the
unspecified-undefined-and-implemenation-defined
branch
from
01687e9 to
2d49333
Compare
|
lgtm |
1 similar comment
|
lgtm |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I had been unaware of formal distinctions between these terms until @stephenrwalli called it out in the context of his suggestion to use “implementation defined” for uploading
application/vnd.oci.image.layer.nondistributable.tar+gzip. 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 “rationale for the C99 standard” link text seems pretty informal, but that's what WG14 uses to refer to the document.