Cleanup the spec a bit to remove WG/git text that's not really part of the spec

Doug Davis · Doug Davis · commit 082ebc13b5a4 · 2016-11-15T08:05:30.000-08:00
renamed an href to "container-namespace2" to avoid a dup-warning msg from
the PDF generator

Signed-off-by: Doug Davis &lt;dug@us.ibm.com&gt;
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,3 @@
 output
 schema/validate
-code-of-conduct.md
 version.md
diff --git a/Makefile b/Makefile
@@ -21,13 +21,8 @@ endif
 # These docs are in an order that determines how they show up in the PDF/HTML docs.
 DOC_FILES := \
 	version.md \
-	README.md \
-	code-of-conduct.md \
+	spec.md \
 	principles.md \
-	style.md \
-	ROADMAP.md \
-	implementations.md \
-	project.md \
 	bundle.md \
 	runtime.md \
 	runtime-linux.md \
@@ -54,9 +49,6 @@ $(OUTPUT_DIRNAME)/$(DOC_FILENAME).html: $(DOC_FILES)
 	$(PANDOC) -f markdown_github -t html5 -o $(PANDOC_DST)$@ $(patsubst %,$(PANDOC_SRC)%,$(DOC_FILES))
 endif
 
-code-of-conduct.md:
-	curl -o $@ https://raw.githubusercontent.com/opencontainers/tob/d2f9d68c1332870e40693fe077d311e0742bc73d/code-of-conduct.md
-
 version.md: ./specs-go/version.go
 	go run ./.tool/version-doc.go > $@
 
@@ -105,5 +97,5 @@ endif
 .PHONY: clean
 clean:
 	rm -rf $(OUTPUT_DIRNAME) *~
-	rm -f code-of-conduct.md version.md
+	rm -f version.md
 
diff --git a/README.md b/README.md
@@ -2,38 +2,17 @@
 
 The [Open Container Initiative](http://www.opencontainers.org/) develops specifications for standards on Operating System process and application containers.
 
+The specification can be found [here](spec.md).
 
-Table of Contents
-
-- [Introduction](README.md)
-    - [Code of Conduct](#code-of-conduct)
-    - [Container Principles](principles.md)
-    - [Style and Conventions](style.md)
-    - [Roadmap](ROADMAP.md)
-    - [Implementations](implementations.md)
-    - [project](project.md)
-- [Filesystem Bundle](bundle.md)
-- Runtime and Lifecycle
-    - [General Runtime and Lifecycle](runtime.md)
-    - [Linux-specific Runtime and Lifecycle](runtime-linux.md)
-- Configuration
-    - [General Configuration](config.md)
-    - [Linux-specific Configuration](config-linux.md)
-    - [Solaris-specific Configuration](config-solaris.md)
-    - [Windows-specific Configuration](config-windows.md)
-- [Glossary](glossary.md)
-
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119][rfc2119].
-
-The key words "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the [rationale for the C99 standard][c99-unspecified].
-
-An implementation is not compliant for a given CPU architecture if it fails to satisfy one or more of the MUST, REQUIRED, or SHALL requirements for the protocols it implements.
-An implementation is compliant for a given CPU architecture if it satisfies all the MUST, REQUIRED, and SHALL requirements for the protocols it implements.
-
-Protocols defined by this specification are:
-* Linux containers: [runtime.md](runtime.md), [config.md](config.md), [config-linux.md](config-linux.md), and [runtime-linux.md](runtime-linux.md).
-* Solaris containers: [runtime.md](runtime.md), [config.md](config.md), and [config-solaris.md](config-solaris.md).
-* Windows containers: [runtime.md](runtime.md), [config.md](config.md), and [config-windows.md](config-windows.md).
+[charter]: https://www.opencontainers.org/about/governance
+
+Additional documentation about how this group operates:
+
+- [Code of Conduct](https://github.com/opencontainers/tob/blob/d2f9d68c1332870e40693fe077d311e0742bc73d/code-of-conduct.md)
+- [Style and Conventions](style.md)
+- [Roadmap](ROADMAP.md)
+- [Implementations](implementations.md)
+- [Releases](RELEASES.md)
 
 # Use Cases
 
@@ -66,10 +45,6 @@ Issues are used for bugs and actionable items and longer discussions can happen
 
 The specification and code is licensed under the Apache 2.0 license found in the [LICENSE](./LICENSE) file.
 
-## Code of Conduct
-
-Participation in the OCI community is governed by the [OCI Code of Conduct](https://github.com/opencontainers/tob/blob/d2f9d68c1332870e40693fe077d311e0742bc73d/code-of-conduct.md).
-
 ## Discuss your design
 
 The project welcomes submissions, but please let everyone know what you are working on.
diff --git a/RELEASES.md b/RELEASES.md
@@ -7,6 +7,14 @@ Releases are proposed and adopted or rejected using the usual [project governanc
 An anti-pattern that we want to avoid is heavy development or discussions "late cycle" around major releases.
 We want to build a community that is involved and communicates consistently through all releases instead of relying on "silent periods" as a judge of stability.
 
+## Release Process
+
+* Increment version in [`specs-go/version.go`](specs-go/version.go)
+* `git commit` version increment
+* `git tag` the prior commit (preferably signed tag)
+* `make docs` to produce PDF and HTML copies of the spec
+* Make a release on [github.com/opencontainers/runtime-spec](https://github.com/opencontainers/runtime-spec/releases) for the version. Attach the produced docs.
+
 ## Parallel releases
 
 A single project MAY consider several motions to release in parallel.
@@ -47,5 +55,3 @@ Specifications have a variety of different timelines in their lifecycle.
   Maintainers SHOULD strive to make zero breaking changes during this cycle of release candidates and SHOULD restart the three-candidate count when a breaking change is introduced.
   For example if a breaking change is introduced in v1.0.0-rc2 then the series would end with v1.0.0-rc4 and v1.0.0.
 - Minor and patch releases SHOULD be made on an as-needed basis.
-
-[charter]: https://www.opencontainers.org/about/governance
diff --git a/config-linux.md b/config-linux.md
@@ -562,7 +562,7 @@ Its value is either slave, private, or shared.
 ## Masked Paths
 
 **`maskedPaths`** (array of strings, OPTIONAL) will mask over the provided paths inside the container so that they cannot be read.
-The values MUST be absolute paths in the [container namespace][container-namespace].
+The values MUST be absolute paths in the [container namespace][container-namespace2].
 
 ###### Example
 
@@ -575,7 +575,7 @@ The values MUST be absolute paths in the [container namespace][container-namespa
 ## Readonly Paths
 
 **`readonlyPaths`** (array of strings, OPTIONAL) will set the provided paths as readonly inside the container.
-The values MUST be absolute paths in the [container namespace][container-namespace].
+The values MUST be absolute paths in the [container namespace][container-namespace2].
 
 ###### Example
 
@@ -595,7 +595,7 @@ The values MUST be absolute paths in the [container namespace][container-namespa
     "mountLabel": "system_u:object_r:svirt_sandbox_file_t:s0:c715,c811"
 ```
 
-[container-namespace]: glossary.md#container_namespace
+[container-namespace2]: glossary.md#container_namespace
 [cgroup-v1]: https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt
 [cgroup-v1-blkio]: https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt
 [cgroup-v1-cpusets]: https://www.kernel.org/doc/Documentation/cgroup-v1/cpusets.txt
diff --git a/project.md b/project.md
diff --git a/spec.md b/spec.md
@@ -0,0 +1,33 @@
+# Open Container Initiative Runtime Specification
+
+The [Open Container Initiative](http://www.opencontainers.org/) develops specifications for standards on Operating System process and application containers.
+
+Protocols defined by this specification are:
+* Linux containers: [runtime.md](runtime.md), [config.md](config.md), [config-linux.md](config-linux.md), and [runtime-linux.md](runtime-linux.md).
+* Solaris containers: [runtime.md](runtime.md), [config.md](config.md), and [config-solaris.md](config-solaris.md).
+* Windows containers: [runtime.md](runtime.md), [config.md](config.md), and [config-windows.md](config-windows.md).
+
+# Table of Contents
+
+- [Introduction](spec.md)
+    - [Notational Conventions](#notational-conventions)
+    - [Container Principles](principles.md)
+- [Filesystem Bundle](bundle.md)
+- [Runtime and Lifecycle](runtime.md)
+    - [Linux-specific Runtime and Lifecycle](runtime-linux.md)
+- [Configuration](config.md)
+    - [Linux-specific Configuration](config-linux.md)
+    - [Solaris-specific Configuration](config-solaris.md)
+    - [Windows-specific Configuration](config-windows.md)
+- [Glossary](glossary.md)
+
+# Notational Conventions
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119][rfc2119].
+
+The key words "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the [rationale for the C99 standard][c99-unspecified].
+
+An implementation is not compliant for a given CPU architecture if it fails to satisfy one or more of the MUST, REQUIRED, or SHALL requirements for the protocols it implements.
+An implementation is compliant for a given CPU architecture if it satisfies all the MUST, REQUIRED, and SHALL requirements for the protocols it implements.
+
+[rfc2119]: http://tools.ietf.org/html/rfc2119
