Clean-up spec to remove non-spec-ish items

Signed-off-by: Doug Davis <[email protected]>
opencontainers · Nov 16, 2016 · b0a5eff · b0a5eff
1 parent 7cab1f8
commit b0a5eff
Show file tree

Hide file tree

Showing 5 changed files with 62 additions and 56 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,2 @@
-code-of-conduct.md
 /oci-validate-examples
 output
diff --git a/Makefile b/Makefile
@@ -21,9 +21,7 @@ endif
 
 # These docs are in an order that determines how they show up in the PDF/HTML docs.
 DOC_FILES := \
-	README.md \
-	code-of-conduct.md \
-	project.md \
+	spec.md \
 	media-types.md \
 	descriptor.md \
 	image-layout.md \
@@ -77,9 +75,6 @@ $(OUTPUT_DIRNAME)/$(DOC_FILENAME).html: $(DOC_FILES) $(FIGURE_FILES)
 	ls -sh $(shell readlink -f $@)
 endif
 
-code-of-conduct.md:
-	curl -o $@ https://raw.githubusercontent.com/opencontainers/tob/d2f9d68c1332870e40693fe077d311e0742bc73d/code-of-conduct.md
-
 validate-examples:
 	go test -run TestValidate ./schema
 

diff --git a/README.md b/README.md
@@ -1,50 +1,15 @@
 # Open Container Initiative Image Format Specification
 
 The OCI Image Format project creates and maintains the software shipping container image format spec (OCI Image Format).
-The goal of this specification is to enable the creation of interoperable tools for building, transporting, and preparing a container image to run.
 
-## Table of Contents
+The specification can be found [here](spec.md).
 
-- [Introduction](README.md)
-    - [Code of Conduct](#code-of-conduct)
-    - [Project Documentation](project.md)
-    - [Media Types](media-types.md)
-- [Content Descriptors](descriptor.md)
-- [Image Layout](image-layout.md)
-- [Image Manifest](manifest.md)
-- [Image Manifest List](manifest-list.md)
-- [Filesystem Layers](layer.md)
-- [Image Configuration](config.md)
-- [Canonicalization](canonicalization.md)
+Additional documentation about how this group operates:
 
-## Overview
-
-This specification defines how to create an OCI Image, which will generally be done by a build system, and output an [image manifest](manifest.md), a set of [filesystem layers](layer.md), and an [image configuration](config.md).
-At a high level the image manifest contains metadata about the contents and dependencies of the image including the content-addressable identity of one or more [filesystem layer changeset](layer.md) archives that will be unpacked to make up the final runnable filesystem.
-The image configuration includes information such as application arguments, environments, etc.
-The combination of the image manifest, image configuration, and one or more filesystem layers is called the "OCI Image".
-
-The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119) (Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997).
-
-The keywords "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the [rationale for the C99 standard][c99-unspecified].
-
-![](img/build-diagram.png)
-
-Once built the OCI Image can then be discovered by name, downloaded, verified by hash, trusted through a signature, and unpacked into an [OCI Runtime Bundle](https://github.com/opencontainers/runtime-spec/blob/master/bundle.md).
-
-![](img/run-diagram.png)
-
-## Understanding the Specification
-
-The [OCI Image Media Types](media-types.md) document is a starting point to understanding the overall structure of the specification.
-
-The high-level components of the spec include:
-
-* An archival format for container images, consisting of an [image manifest](manifest.md), an [image layout](image-layout.md), a set of [filesystem layers](layer.md), and [image configuration](config.md) (base OCI layer)
-* A [process of referencing container images by a cryptographic hash of their content](descriptor.md) (base OCI layer)
-* A format for [storing CAS blobs and references to them](image-layout.md) (optional OCI layer)
-* Signatures that are based on signing image content address (optional OCI layer)
-* Naming that is federated based on DNS and can be delegated (optional OCI layer)
+- [Code of Conduct](https://github.com/opencontainers/tob/blob/d2f9d68c1332870e40693fe077d311e0742bc73d/code-of-conduct.md)
+- [Roadmap](#roadmap)
+- [Releases](RELEASES.md)
+- [Project Documentation](project.md)
 
 The _optional_ and _base_ layers of all OCI projects are tracked in the [OCI Scope Table](https://www.opencontainers.org/governance/oci-scope-table).
 
@@ -96,10 +61,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` file of this repository.
 
-## 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.
@@ -202,6 +163,5 @@ Read more on [How to Write a Git Commit Message](http://chris.beams.io/posts/git
 8. When possible, one keyword to scope the change in the subject (i.e. "README: ...", "runtime: ...")
 
 
-[c99-unspecified]: http://www.open-std.org/jtc1/sc22/wg14/www/C99RationaleV5.10.pdf#page=18
 [UberConference]: https://www.uberconference.com/opencontainers
 [irc-logs]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/
diff --git a/manifest-list.md b/manifest-list.md
@@ -41,12 +41,12 @@ This section defines the `application/vnd.oci.image.manifest.list.v1+json` [medi
     - **`architecture`** *string*
 
         This REQUIRED property specified the CPU architecture.
-        Manifest lists SHOULD use, and implementations SHOULD understand, values [supported by runtime-spec's `platform.arch`][runtime-platform].
+        Manifest lists SHOULD use, and implementations SHOULD understand, values [supported by runtime-spec's `platform.arch`][runtime-platform2].
 
     - **`os`** *string*
 
         This REQUIRED property specifies the operating system.
-        Manifest lists SHOULD use, and implementations SHOULD understand, values [supported by runtime-spec's `platform.os`][runtime-platform].
+        Manifest lists SHOULD use, and implementations SHOULD understand, values [supported by runtime-spec's `platform.os`][runtime-platform2].
 
     - **`os.version`** *string*
 
@@ -118,4 +118,4 @@ Instead they MUST ignore unknown properties.
 }
 ```
 
-[runtime-platform]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc2/config.md#platform
+[runtime-platform2]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc2/config.md#platform
diff --git a/spec.md b/spec.md
@@ -0,0 +1,52 @@
+# Open Container Initiative Image Format Specification
+
+This specification defines how to create an OCI Image, which will generally be done by a build system, and output an [image manifest](manifest.md), a set of [filesystem layers](layer.md), and an [image configuration](config.md).
+
+The goal of this specification is to enable the creation of interoperable tools for building, transporting, and preparing a container image to run.
+
+## Table of Contents
+
+- [Introduction](spec.md)
+- [Notational Conventions](#notational-conventions)
+- [Overview](#overview)
+	- [Understanding the Specification](#understanding-the-specification)
+    - [Media Types](media-types.md)
+- [Content Descriptors](descriptor.md)
+- [Image Layout](image-layout.md)
+- [Image Manifest](manifest.md)
+- [Image Manifest List](manifest-list.md)
+- [Filesystem Layers](layer.md)
+- [Image Configuration](config.md)
+- [Canonicalization](canonicalization.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](http://tools.ietf.org/html/rfc2119) (Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997).
+
+The key words "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the [rationale for the C99 standard][c99-unspecified].
+
+# Overview
+
+At a high level the image manifest contains metadata about the contents and dependencies of the image including the content-addressable identity of one or more [filesystem layer changeset](layer.md) archives that will be unpacked to make up the final runnable filesystem.
+The image configuration includes information such as application arguments, environments, etc.
+The combination of the image manifest, image configuration, and one or more filesystem layers is called the "OCI Image".
+
+![](img/build-diagram.png)
+
+Once built the OCI Image can then be discovered by name, downloaded, verified by hash, trusted through a signature, and unpacked into an [OCI Runtime Bundle](https://github.com/opencontainers/runtime-spec/blob/master/bundle.md).
+
+![](img/run-diagram.png)
+
+## Understanding the Specification
+
+The [OCI Image Media Types](media-types.md) document is a starting point to understanding the overall structure of the specification.
+
+The high-level components of the spec include:
+
+* An archival format for container images, consisting of an [image manifest](manifest.md), an [image layout](image-layout.md), a set of [filesystem layers](layer.md), and [image configuration](config.md) (base OCI layer)
+* A [process of referencing container images by a cryptographic hash of their content](descriptor.md) (base OCI layer)
+* A format for [storing CAS blobs and references to them](image-layout.md) (optional OCI layer)
+* Signatures that are based on signing image content address (optional OCI layer)
+* Naming that is federated based on DNS and can be delegated (optional OCI layer)
+
+[c99-unspecified]: http://www.open-std.org/jtc1/sc22/wg14/www/C99RationaleV5.10.pdf#page=18