policy: Collect established policies in a discoverable location

wking · wking · commit c41523b6e268 · 2015-12-29T20:36:56.000-08:00
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 (1873498, 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>
diff --git a/Makefile b/Makefile
@@ -4,6 +4,7 @@ DOC_FILES := \
 	README.md \
 	code-of-conduct.md \
 	principles.md \
+	policy.md \
 	ROADMAP.md \
 	implementations.md \
 	bundle.md \
diff --git a/README.md b/README.md
@@ -6,6 +6,7 @@
 Table of Contents
 
 - [Container Principles](principles.md)
+- [Specification Policies](policy.md)
 - [Filesystem Bundle](bundle.md)
 - Configuration
   - [Container Configuration](config.md)
diff --git a/policy.md b/policy.md
@@ -0,0 +1,19 @@
+# Policies and conventions
+
+## Traditionally hex settings should use JSON integers, not JSON strings
+
+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
+[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
