Update description of how deployment works

It's not Morph-specific any more.

Change-Id: I0742c21de14f6bb660ad60dd3b37242fd3067711

1 files changed, 15 insertions, 33 deletions

diff --git a/spec.mdwn b/spec.mdwn
index 47fbfa0..bc542d2 100644
--- a/spec.mdwn
+++ b/spec.mdwn
@@ -65,17 +65,6 @@ on versions.
 To find all the Baserock definition files in the repo, tooling can recursively
 scan the contents of the repo for files matching the glob pattern "\*.morph".
 
-Deployment tooling should look in the toplevel directory /only/ for files
-matching the following globs. (The purpose of these files is described in the
-"deployment" section below).
-
-  - `\*.check`
-  - `\*.check.help`
-  - `\*.configure`
-  - `\*.configure.help`
-  - `\*.write`
-  - `\*.write.help`
-
 Definitions file syntax
 -----------------------
 
@@ -265,11 +254,7 @@ Example system:
 
 ### Deployment definitions: Clusters
 
-**NOTE**: The deployment mechanism specified here is quite abstract. Most of
-the code used to do real-world deployments is currently tied to [Morph] and
-kept in [morph.git].
-
-For 'deployment', [Morph] defines an API for running 'extensions'. The
+For 'deployment', Baserock defines an API for running 'extensions'. The
 'cluster' and 'system' definitions together describe what extensions should be
 run, and what should be set in their environment, in order to deploy the
 system. See the "Deployment extension API" section below for how to find and
@@ -293,8 +278,8 @@ list of ways to deploy them. Use the following field:
     * **deploy**: a mapping where each key identifies a
         system and each system has at least the following keys:
 
-        * **type**: identifies the type of deployment e.g. (kvm,
-            pxeboot), and thus what '.write' extension should be used.
+        * **type**: identifies the relative path, without extension, to the
+            '.write' program that should be used for this system.
         * **location**: where the deployed system should end up
             at. The syntax depends on the '.write' extension chosen in the
             'type' field.
@@ -395,10 +380,6 @@ FIXME: The `TARGET` and `TARGET_STAGE1` fields are specific to building GNU/Linu
 Deployment extension API
 ------------------------
 
-**NOTE**: This section is more of an explaination of how the `morph deploy`
-command works than a general-purpose spec, in places. We hope to fix that in
-future.
-
 As noted in the previous section: within this document, consider "deployment"
 to be a process of first post-processing a filesystem tree with one or more
 'configure extensions', then performing an operation to convert and/or transfer
@@ -409,8 +390,8 @@ the filesystem tree using a 'write extension'.
 A Baserock deployment tool should, for each labelled deployment in the
 'cluster', follow this sequence.
 
-1. Run the .check extension for that deployment 'type', if one exists. Abort
-   now, if it fails.
+1. Run the program '$type.check' (where $type is the value of the 'type'
+   field), if it exists. If it fails, exit now with an error.
 
    The .check extensions exist only to work around the fact that (2), (3) and
    (4) may be slow, because programs that wait several minutes just to raise an
@@ -423,9 +404,9 @@ A Baserock deployment tool should, for each labelled deployment in the
    intention is that the result of the subsystem deployments end up *inside*
    the temporary directory created in step 2 for the 'outer' deployment.
 
-4. Run each .configure extension that was specified in the
-   `configuration-extensions` field of the system morphology. The order of
-   running these is, sadly, unspecified.
+4. For each path in the `configuration-extensions` field of the corresponding
+   system morphology, run `$path.configure`. The order of running these is,
+   sadly, unspecified.
 
 5. Run the .write extension for that deployment 'type'.
 
@@ -434,13 +415,14 @@ and temporary data can be removed.
 
 ### Locating and running extensions
 
-Deployment extensions are executable files that live in the top level directory
-of the definitions.git repo. Configure extensions have the extension
-`.configure`, check extensions have the extension `.check`, and write
-extensions have the extension `.write`.
+The deployment extensions must live in the definitions repository. They can be
+in a subdirectory, we recommend `extensions/`.
 
-[Morph] will look for extensions inside the 'morphlib' Python package, in the
-`exts/` dir, before looking in the definitions.git repo.
+> Previously extensions could and did live in the build tool's code. This was a
+bad idea because we needed to define a new VERSION every time we changed
+anything in the API of any deployment extension that the build tool provide,
+and every new build tool that wanted to do deployment needed to reimplement or
+duplicate every such extension.
 
 An extension must be executable using the [POSIX `exec()` system call]. We
 encourage writing them as Python scripts and using a `#!/usr/bin/env python`