From 408412ba80a90449194e5a00c14c91956c6f10f7 Mon Sep 17 00:00:00 2001
From: "W. Trevor King" <wking@tremily.us>
Date: Tue, 29 Dec 2015 20:31:10 -0800
Subject: [PATCH] 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>
---
 Makefile  |  1 +
 README.md |  1 +
 style.md  | 21 +++++++++++++++++++++
 3 files changed, 23 insertions(+)
 create mode 100644 style.md

diff --git a/Makefile b/Makefile
index 9d5937ec2..a35e0ac2d 100644
--- a/Makefile
+++ b/Makefile
@@ -4,6 +4,7 @@ DOC_FILES := \
 	README.md \
 	code-of-conduct.md \
 	principles.md \
+	style.md \
 	ROADMAP.md \
 	implementations.md \
 	bundle.md \
diff --git a/README.md b/README.md
index e838b0188..13cb46937 100644
--- a/README.md
+++ b/README.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)
diff --git a/style.md b/style.md
new file mode 100644
index 000000000..e54956b38
--- /dev/null
+++ b/style.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