5.3 KiB
Style and conventions
One sentence per line
To keep consistency throughout the Markdown files in the Open Container spec all files should be formatted one sentence per line. This fixes two things: it makes diffing easier with git and it resolves fights about line wrapping length. For example, this paragraph will span three lines in the Markdown source.
Traditionally hex settings should use JSON integers, not JSON strings
For example, "classID": 1048577 instead of "classID": "0x100001".
The config JSON isn't enough of a UI to be worth jumping through string <-> integer hoops to support an 0x… form (source).
Constant names should keep redundant prefixes
For example, CAP_KILL instead of KILL in process.capabilities.
The redundancy reduction from removing the namespacing prefix is not useful enough to be worth trimming the upstream identifier (source).
Optional settings should not have pointer Go types
Because in many cases the Go default for the type is a no-op in the spec (sources here, here, and here). The exceptions are entries where we need to distinguish between “not set” and “set to the Go default for that type” (source), and this decision should be made on a per-setting case.
Links
Internal links should be relative links when linking to content within the repository. Internal links should be used inline.
External links should be collected at the bottom of a markdown file and used as referenced links. See 'Referenced Links' in this markdown quick reference. The use of referenced links in the markdown body helps to keep files clean and organized. This also facilitates updates of external link targets on a per-file basis.
Referenced links should be kept in two alphabetically sorted sets, a general reference section followed by a man page section.
To keep Pandoc happy, duplicate naming of links within pages listed in the Makefile's DOC_FILES variable should be avoided by appending an _N to the link tagname, where N is some number not currently in use.
The organization and style of an existing reference section should be maintained unless it violates these style guidelines.
An exception to these rules is when a URL is needed contextually, for example when showing an explicit link to the reader.
Examples
Anchoring
For any given section that provides a notable example, it is ideal to have it denoted with markdown headers. The level of header should be such that it is a subheader of the header it is an example of.
Example
## Some Topic
### Some Subheader
#### Further Subheader
##### Example
To use Further Subheader, ...
### Example
To use Some Topic, ...
Content
Where necessary, the values in the example can be empty or unset, but accommodate with comments regarding this intention.
Where feasible, the content and values used in an example should convey the fullest use of the data structures concerned. Most commonly onlookers will intend to copy-and-paste a "working example". If the intention of the example is to be a fully utilized example, rather than a copy-and-paste example, perhaps add a comment as such.
### Example
{
"foo": null,
"bar": ""
}
vs.
### Example
Following is a fully populated example (not necessarily for copy/paste use)
{
"foo": [
1,
2,
3
],
"bar": "waffles",
"bif": {
"baz": "potatoes"
}
}
Links
The following is an example of different types of links. This is shown as a complete markdown file, where the referenced links are at the bottom.
The specification repository's [glossary](glossary.md) is where readers can find definitions of commonly used terms.
Readers may click through to the [Open Containers namespace][open-containers] on [GitHub][github].
The URL for the Open Containers link above is: https://github.com/opencontainers
[github]: https://github.com
[open-containers]: https://github.com/opencontainers