More examples in spec
Table of contents
- What are the challenges that we are trying to solve?
- What ideas do we have for how to address these challenges?
- How do these ideas break down into…
- Questions?
- What pre-existing work or software can support these ideas?
- Relevant OCI Issues
What are the challenges that we are trying to solve?
The OCI specs have lots of examples, but they tend to be (a) snippets of (b) the common cases. However, implementers will have trouble with edge cases and getting everything to work together. So, the spec needs more examples to illustrate:
-
edge cases
-
complete interactions, e.g. a sample image in a tarball or a complete transcript of a pull session
What ideas do we have for how to address these challenges?
Add edge case and complete examples to the specification text.
There is some overlap here with “Conformance tests”. The point here is slightly different, though: it’s to illustrate for readers tricky parts of the spec.
How do these ideas break down into…
Already existing OCI specs?
This idea is relevant to all existing OCI specifications. Ideally there would be a standard means to define and display examples for the reader to quickly understand. If a documentation or similar working group is accepted this could be worked on.