1# <a name="styleAndConventions" />Style and conventions
2
3## <a name="styleOneSentence" />One sentence per line
4
5To keep consistency throughout the Markdown files in the Open Container spec all files should be formatted one sentence per line.
6This fixes two things: it makes diffing easier with git and it resolves fights about line wrapping length.
7For example, this paragraph will span three lines in the Markdown source.
8
9## <a name="styleHex" />Traditionally hex settings should use JSON integers, not JSON strings
10
11For example, [`"classID": 1048577`](config-linux.md#network) instead of `"classID": "0x100001"`.
12The 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]).
13
14## <a name="styleConstantNames" />Constant names should keep redundant prefixes
15
16For example, `CAP_KILL` instead of `KILL` in [**`process.capabilities`**](config.md#process).
17The redundancy reduction from removing the namespacing prefix is not useful enough to be worth trimming the upstream identifier ([source][keep-prefix]).
18
19## <a name="styleOptionalSettings" />Optional settings should not have pointer Go types
20
21Because in many cases the Go default for the type is a no-op in the spec (sources [here][no-pointer-for-strings], [here][no-pointer-for-slices], and [here][no-pointer-for-boolean]).
22The exceptions are entries where we need to distinguish between “not set” and “set to the Go default for that type” ([source][pointer-when-updates-require-changes]), and this decision should be made on a per-setting case.
23
24## Links
25
26Internal links should be [relative links][markdown-relative-links] when linking to content within the repository.
27Internal links should be used inline.
28
29External links should be collected at the bottom of a markdown file and used as referenced links.
30See 'Referenced Links' in this [markdown quick reference][markdown-quick-reference].
31The use of referenced links in the markdown body helps to keep files clean and organized.
32This also facilitates updates of external link targets on a per-file basis.
33
34Referenced links should be kept in two alphabetically sorted sets, a general reference section followed by a man page section.
35To 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.
36The organization and style of an existing reference section should be maintained unless it violates these style guidelines.
37
38An exception to these rules is when a URL is needed contextually, for example when showing an explicit link to the reader.
39
40## Examples
41
42### <a name="styleAnchoring" />Anchoring
43
44For any given section that provides a notable example, it is ideal to have it denoted with [markdown headers][markdown-headers].
45The level of header should be such that it is a subheader of the header it is an example of.
46
47#### Example
48
49```markdown
50## Some Topic
51
52### Some Subheader
53
54#### Further Subheader
55
56##### Example
57
58To use Further Subheader, ...
59
60### Example
61
62To use Some Topic, ...
63
64```
65
66### <a name="styleContent" />Content
67
68Where necessary, the values in the example can be empty or unset, but accommodate with comments regarding this intention.
69
70Where feasible, the content and values used in an example should convey the fullest use of the data structures concerned.
71Most commonly onlookers will intend to copy-and-paste a "working example".
72If 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.
73
74```markdown
75### Example
76```
77```json
78{
79 "foo": null,
80 "bar": ""
81}
82```
83
84**vs.**
85
86```markdown
87### Example
88
89Following is a fully populated example (not necessarily for copy/paste use)
90```
91```json
92{
93 "foo": [
94 1,
95 2,
96 3
97 ],
98 "bar": "waffles",
99 "bif": {
100 "baz": "potatoes"
101 }
102}
103```
104
105### Links
106
107The following is an example of different types of links.
108This is shown as a complete markdown file, where the referenced links are at the bottom.
109
110```markdown
111The specification repository's [glossary](glossary.md) is where readers can find definitions of commonly used terms.
112
113Readers may click through to the [Open Containers namespace][open-containers] on [GitHub][github].
114
115The URL for the Open Containers link above is: https://github.com/opencontainers
116
117
118[github]: https://github.com
119[open-containers]: https://github.com/opencontainers
120```
121
122
123[integer-over-hex]: https://github.com/opencontainers/runtime-spec/pull/267#r48360013
124[keep-prefix]: https://github.com/opencontainers/runtime-spec/pull/159#issuecomment-138728337
125[no-pointer-for-boolean]: https://github.com/opencontainers/runtime-spec/pull/290#r50296396
126[no-pointer-for-slices]: https://github.com/opencontainers/runtime-spec/pull/316#r50782982
127[no-pointer-for-strings]: https://github.com/opencontainers/runtime-spec/pull/653#issue-200439192
128[pointer-when-updates-require-changes]: https://github.com/opencontainers/runtime-spec/pull/317#r50932706
129[markdown-headers]: https://help.github.com/articles/basic-writing-and-formatting-syntax/#headings
130[markdown-quick-reference]: https://en.support.wordpress.com/markdown-quick-reference
131[markdown-relative-links]: https://help.github.com/articles/basic-writing-and-formatting-syntax/#relative-links
View as plain text