style: Collect established styles in a discoverable location
So we have something to cite to avoid rehashing established decisions.
Provide some motivation and links to the backing discussion so folks
can re-open these if they have new information that wasn't covered in
the original decision.
Like the glossary (18734986
, glossary: Provide a quick overview of
important terms, 2015-08-11, #107), I've used subsection titles for
each entry to get link anchors.
Signed-off-by: W. Trevor King <wking@tremily.us>
This commit is contained in:
parent
2fd5ad660e
commit
408412ba80
1
Makefile
1
Makefile
|
@ -4,6 +4,7 @@ DOC_FILES := \
|
|||
README.md \
|
||||
code-of-conduct.md \
|
||||
principles.md \
|
||||
style.md \
|
||||
ROADMAP.md \
|
||||
implementations.md \
|
||||
bundle.md \
|
||||
|
|
|
@ -6,6 +6,7 @@
|
|||
Table of Contents
|
||||
|
||||
- [Container Principles](principles.md)
|
||||
- [Specification Style](style.md)
|
||||
- [Filesystem Bundle](bundle.md)
|
||||
- Configuration
|
||||
- [Container Configuration](config.md)
|
||||
|
|
|
@ -0,0 +1,21 @@
|
|||
# Style and conventions
|
||||
|
||||
## 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]).
|
||||
|
||||
[capabilities]: config-linux.md#capabilities
|
||||
[class-id]: runtime-config-linux.md#network
|
||||
[integer-over-hex]: https://github.com/opencontainers/specs/pull/267#discussion_r48360013
|
||||
[keep-prefix]: https://github.com/opencontainers/specs/pull/159#issuecomment-138728337
|
||||
[optional-pointer]: https://github.com/opencontainers/specs/pull/233#discussion_r47829711
|
Loading…
Reference in New Issue