jasder
/
runc
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
runc/style.md

27 lines
1.6 KiB
Markdown
Raw Normal View History

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>
2015-12-30 12:31:10 +08:00
# Style and conventions
## Traditionally hex settings should use JSON integers, not JSON strings
For example, [`"classID": 1048577`][class-id] instead of `"classID": "0x100001"`.
style: remove unicode character pandoc/LaTeX is not happy with this shady character. ``` ! Package inputenc Error: Unicode char \u8:↔ not set up for use with LaTeX. ``` Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>
2016-01-15 04:18:52 +08:00
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]).
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>
2015-12-30 12:31:10 +08:00
## 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]).
style: Document recent Go-pointer exceptions The general rule seems to be: If Go's default value has the same semantics we'd use for an unset value, don't bother with a pointer. I'm not sure how well that squares with [1]: We want a consistent way to identify unset settings. But if the falsy values count as "unset", maybe the "null is a consistent identifier for unset" approach was never really viable. Qiang points out that pointers are required to opt-out of boolean settings where both true and false would require action [2], so I've worded the exception to only apply when the Go default for the type is expicitly a no-op in the spec. I'm also not sure if the new style extends to integers where zero has the same semantics as unset values. It sounds like Michael was ok with no pointers for those values [3], but OOMScoreAdj (where zero clearly means "do nothing") got a pointer in #233 [4]. More clarity on the threshold would be nice; in this commit I've laid out the logic and not explicitly listed the types it applies to. [1]: https://github.com/opencontainers/specs/pull/233#discussion_r47829711 [2]: https://github.com/opencontainers/specs/pull/317/files#r50932706 [3]: https://github.com/opencontainers/specs/pull/233#issuecomment-155250592 [4]: https://github.com/opencontainers/specs/pull/233/files#diff-34c30be66233f08b447fb608ea0e66bbR206 Signed-off-by: W. Trevor King <wking@tremily.us>
2016-01-26 13:00:30 +08:00
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]).
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>
2015-12-30 12:31:10 +08:00
[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
style: Document recent Go-pointer exceptions The general rule seems to be: If Go's default value has the same semantics we'd use for an unset value, don't bother with a pointer. I'm not sure how well that squares with [1]: We want a consistent way to identify unset settings. But if the falsy values count as "unset", maybe the "null is a consistent identifier for unset" approach was never really viable. Qiang points out that pointers are required to opt-out of boolean settings where both true and false would require action [2], so I've worded the exception to only apply when the Go default for the type is expicitly a no-op in the spec. I'm also not sure if the new style extends to integers where zero has the same semantics as unset values. It sounds like Michael was ok with no pointers for those values [3], but OOMScoreAdj (where zero clearly means "do nothing") got a pointer in #233 [4]. More clarity on the threshold would be nice; in this commit I've laid out the logic and not explicitly listed the types it applies to. [1]: https://github.com/opencontainers/specs/pull/233#discussion_r47829711 [2]: https://github.com/opencontainers/specs/pull/317/files#r50932706 [3]: https://github.com/opencontainers/specs/pull/233#issuecomment-155250592 [4]: https://github.com/opencontainers/specs/pull/233/files#diff-34c30be66233f08b447fb608ea0e66bbR206 Signed-off-by: W. Trevor King <wking@tremily.us>
2016-01-26 13:00:30 +08:00
[no-pointer-for-boolean]: https://github.com/opencontainers/specs/pull/290#discussion_r50296396
[no-pointer-for-slices]: https://github.com/opencontainers/specs/pull/316/files#r50782982
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>
2015-12-30 12:31:10 +08:00
[optional-pointer]: https://github.com/opencontainers/specs/pull/233#discussion_r47829711
style: Document recent Go-pointer exceptions The general rule seems to be: If Go's default value has the same semantics we'd use for an unset value, don't bother with a pointer. I'm not sure how well that squares with [1]: We want a consistent way to identify unset settings. But if the falsy values count as "unset", maybe the "null is a consistent identifier for unset" approach was never really viable. Qiang points out that pointers are required to opt-out of boolean settings where both true and false would require action [2], so I've worded the exception to only apply when the Go default for the type is expicitly a no-op in the spec. I'm also not sure if the new style extends to integers where zero has the same semantics as unset values. It sounds like Michael was ok with no pointers for those values [3], but OOMScoreAdj (where zero clearly means "do nothing") got a pointer in #233 [4]. More clarity on the threshold would be nice; in this commit I've laid out the logic and not explicitly listed the types it applies to. [1]: https://github.com/opencontainers/specs/pull/233#discussion_r47829711 [2]: https://github.com/opencontainers/specs/pull/317/files#r50932706 [3]: https://github.com/opencontainers/specs/pull/233#issuecomment-155250592 [4]: https://github.com/opencontainers/specs/pull/233/files#diff-34c30be66233f08b447fb608ea0e66bbR206 Signed-off-by: W. Trevor King <wking@tremily.us>
2016-01-26 13:00:30 +08:00
[pointer-when-updates-require-changes]: https://github.com/opencontainers/specs/pull/317/files#r50932706