133 lines
5.3 KiB
Markdown
133 lines
5.3 KiB
Markdown
# <a name="styleAndConventions" />Style and conventions
|
|
|
|
## <a name="styleOneSentence" />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.
|
|
|
|
## <a name="styleHex" />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]).
|
|
|
|
## <a name="styleConstantNames" />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]).
|
|
|
|
## <a name="styleOptionalSettings" />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][no-pointer-for-strings], [here][no-pointer-for-slices], and [here][no-pointer-for-boolean]).
|
|
The 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.
|
|
|
|
## Links
|
|
|
|
Internal links should be [relative links][markdown-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][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
|
|
|
|
### <a name="styleAnchoring" />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, ...
|
|
|
|
```
|
|
|
|
### <a name="styleContent" />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"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 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.
|
|
|
|
```markdown
|
|
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
|
|
```
|
|
|
|
|
|
[capabilities]: config-linux.md#capabilities
|
|
[class-id]: config-linux.md#network
|
|
[integer-over-hex]: https://github.com/opencontainers/runtime-spec/pull/267#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#r50296396
|
|
[no-pointer-for-slices]: https://github.com/opencontainers/runtime-spec/pull/316#r50782982
|
|
[no-pointer-for-strings]: https://github.com/opencontainers/runtime-spec/pull/653#issue-200439192
|
|
[pointer-when-updates-require-changes]: https://github.com/opencontainers/runtime-spec/pull/317#r50932706
|
|
[markdown-headers]: https://help.github.com/articles/basic-writing-and-formatting-syntax/#headings
|
|
[markdown-quick-reference]: https://en.support.wordpress.com/markdown-quick-reference
|
|
[markdown-relative-links]: https://help.github.com/articles/basic-writing-and-formatting-syntax/#relative-links
|