98 lines
3.3 KiB
Markdown
98 lines
3.3 KiB
Markdown
|
# 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`][class-id] 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][integer-over-hex]).
|
||
|
|
|
||
|
|
## Constant names should keep redundant prefixes
|
||
|
|
|
||
|
|
For example, `CAP_KILL` instead of `KILL` in [**`linux.capabilities`**][capabilities].
|
||
|
|
The redundancy reduction from removing the namespacing prefix is not useful enough to be worth trimming the upstream identifier ([source][keep-prefix]).
|
||
|
|
|
||
|
|
## Optional settings should have pointer Go types
|
||
|
|
|
||
|
|
So we have a consistent way to identify unset values ([source][optional-pointer]).
|
||
|
|
The exceptions are entries where the Go default for the type is a no-op in the spec, in which case `omitempty` is sufficient and no pointer is needed (sources [here][no-pointer-for-slices], [here][no-pointer-for-boolean], and [here][pointer-when-updates-require-changes]).
|
||
|
|
|
||
|
|
## Examples
|
||
|
|
|
||
|
|
### Anchoring
|
||
|
|
|
||
|
|
For any given section that provides a notable example, it is ideal to have it denoted with [markdown headers][markdown-headers].
|
||
|
|
The level of header should be such that it is a subheader of the header it is an example of.
|
||
|
|
|
||
|
|
#### Example
|
||
|
|
|
||
|
|
```markdown
|
||
|
|
## 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.
|
||
|
|
|
||
|
|
```markdown
|
||
|
|
### Example
|
||
|
|
```
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"foo": null,
|
||
|
|
"bar": ""
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
**vs.**
|
||
|
|
|
||
|
|
```markdown
|
||
|
|
### Example
|
||
|
|
|
||
|
|
Following is a fully populated example (not necessarily for copy/paste use)
|
||
|
|
```
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"foo": [
|
||
|
|
1,
|
||
|
|
2,
|
||
|
|
3
|
||
|
|
],
|
||
|
|
"bar": "waffles",
|
||
|
|
"bif": {
|
||
|
|
"baz": "potatoes"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
[capabilities]: config-linux.md#capabilities
|
||
|
|
[class-id]: config-linux.md#network
|
||
|
|
[integer-over-hex]: https://github.com/opencontainers/runtime-spec/pull/267#discussion_r48360013
|
||
|
|
[keep-prefix]: https://github.com/opencontainers/runtime-spec/pull/159#issuecomment-138728337
|
||
|
|
[no-pointer-for-boolean]: https://github.com/opencontainers/runtime-spec/pull/290#discussion_r50296396
|
||
|
|
[no-pointer-for-slices]: https://github.com/opencontainers/runtime-spec/pull/316/files#r50782982
|
||
|
|
[optional-pointer]: https://github.com/opencontainers/runtime-spec/pull/233#discussion_r47829711
|
||
|
|
[pointer-when-updates-require-changes]: https://github.com/opencontainers/runtime-spec/pull/317/files#r50932706
|
||
|
|
[markdown-headers]: https://help.github.com/articles/basic-writing-and-formatting-syntax/#headings
|