Merge pull request #349 from vbatts/layer_ordering

Clarify layer ordering

Author: philips

config.md

@@ -141,12 +141,12 @@ Since the [configuration JSON](#image-json) that gets hashed references hashes o
 
     - **diff_ids** *array*, REQUIRED
 
-       An array of layer content hashes (`DiffIDs`), in order from bottom-most to top-most.
+       An array of layer content hashes (`DiffIDs`), in order from first to last.
 
 - **history** *array of objects*, OPTIONAL
 
   Describes the history of each layer.
-  The array is ordered from bottom-most layer to top-most layer.
+  The array is ordered from first to last.
   The object has the following fields:
 
     - **created** *string*, OPTIONAL

image-layout.md

@@ -2,7 +2,12 @@
 
 The OCI Image Layout is a slash separated layout of OCI content-addressable blobs and [location-addressable](https://en.wikipedia.org/wiki/Content-addressable_storage#Content-addressed_vs._location-addressed) references (refs).
 This layout MAY be used in a variety of different transport mechanisms: archive formats (e.g. tar, zip), shared filesystem environments (e.g. nfs), or networked file fetching (e.g. http, ftp, rsync).
-Given an image layout a tool can convert a given ref into a runnable OCI Image Format by finding an appropriate manifest from the manifest list, unpacking the [filesystem layers](layer.md) in the correct order, and then converting the image configuration into an OCI Runtime config.json.
+
+Given an image layout and a ref, a tool can create an [OCI Runtime Specification bundle](https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc2/bundle.md) by:
+
+* Following the ref to find a [manifest](manifest.md#image-manifest), possibly via a [manifest list](manifest.md#manifest-list)
+* Applying the filesystem layers in the specified order
+* Converting the [image configuration](config.md) into an [OCI Runtime Specification config.json](https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc2/config.md)
 
 The image layout has two top level directories:
 

layer.md

@@ -1,7 +1,7 @@
 # Image Layer Filesystem Changeset
 
 This document describes how to serialize a filesystem and filesystem changes like removed files into a blob called a layer.
-One or more layers are ordered on top of each other to create a complete filesystem.
+One or more layers are applied on top of each other to create a complete filesystem.
 This document will use a concrete example to illustrate how to create and consume these filesystem layers.
 
 ## Distributable Format

manifest.md

@@ -159,8 +159,8 @@ Unlike the [Manifest List](#manifest-list), which contains information about a s
 
     Each item in the array MUST be a [descriptor](descriptor.md).
     The array MUST have the base image at index 0.
-    Subsequent layers MUST then follow in the order in which they are to be layered on top of each other.
-    The algorithm to create the final unpacked filesystem layout MUST be to first unpack the layer at index 0, then index 1, and so on.
+    Subsequent layers MUST then follow in stack order (i.e. from `layers[0]` to `layers[len(layers)]`).
+    The final filesystem layout MUST match the result of [applying](layer.md#applying) the layers to an empty directory.
 
     Beyond the [descriptor requirements](descriptor.md#properties), the value has the following additional restrictions: