docs/command-line-interface: Require complete runtime coverage #615
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
I didn't see wording in the previous version of this spec to require runtimes to support the full API, so I've added language for that here. This ensures that callers who only need the specified API will be able to run with an any runtime that is compliant with this API. You could get some way towards this requirement before by leaning on the spec's: > An implementation is compliant if it satisfies all the applicable > MUST, REQUIRED, and SHALL requirements. but there are a number of requirements that currently lack lower-level MUSTs. For example, without the full-API requirement, the only 'delete' requirement would be: > The runtime MUST NOT attempt to read from its stdin. You could have argued that a runtime which did not implement 'delete' satisfied that condition, and so was "compliant" even in the absence of 'delete' support. However, such a runtime would likely break all compliant callers. This commit ensures that such a runtime would clearly be "not compliant". The portability SHOULD NOT is just a hint to callers. If you require extentions beyond this API spec, you'll want to ensure you are comfortable with the potential reduction in compatible runtimes. I've made a patch-level version bump for this commit. If you consider the new requirement to be an extention from the previous spec, there was no way to be a caller rely on any 1.0.0 API calls working. I think the new explicit requirement was an implicit requirement of the 1.0.0, and that sort of typo fix deserves a patch-level bump. For example, we've been requiring runtimes to support 'create' in validation/create.go since those tests landed. This commit just gives us a MUST we can cite for those (and other similar) failures. Signed-off-by: W. Trevor King <wking@tremily.us>
|
LGTM (but I'm not a maintainer) |
|
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 didn't see wording in the previous version of this spec to require runtimes to support the full API, so I've added language for that here. This ensures that callers who only need the specified API will be able to run with an any runtime that is compliant with this API. You could get some way towards this requirement before by leaning on
the spec's:
but there are a number of requirements that currently lack lower-level MUSTs. For example, without the full-API requirement, the only
deleterequirement would be:You could have argued that a runtime which did not implement
deletesatisfied that condition, and so was “compliant” even in the absence ofdeletesupport. However, such a runtime would likely break all compliant callers. This commit ensures that such a runtime would clearly be “not compliant”.The portability SHOULD NOT is just a hint to callers. If you require extentions beyond this API spec, you'll want to ensure you are comfortable with the potential reduction in compatible runtimes.
I've made a patch-level version bump for this commit. If you consider the new requirement to be an extention from the previous spec, there was no way to be a caller rely on any 1.0.0 API calls working. I think the new explicit requirement was an implicit requirement of the 1.0.0, and that sort of typo fix deserves a patch-level bump. For example, we've been requiring runtimes to support
createinvalidation/create.gosince those tests landed. This commit just gives us a MUST we can cite for those (and other similar) failures.