elaborate on the HashDist upgrade procedurev0.2

1 files changed, 39 insertions, 13 deletions

diff --git a/MAINTAIN.md b/MAINTAIN.md
index 0d9d8a9..a9b0075 100644
--- a/MAINTAIN.md
+++ b/MAINTAIN.md
@@ -6,12 +6,30 @@ Copyright © 2016 Paul Garlick <[pgarlick@tourbillion-technology.com](mailto:pga
   notice and this notice are preserved.  This file is offered as-is,
   without any warranty.
 
-*TWEED* applications are upgraded by updating the respective package manager.
-The update procedure installs new versions of the applications and any new
-versions of dependencies.  The update frequency can be determined by keeping an
-eye out for new application versions.  If there are of the order of ten version
-upgrades per year, for example, then a monthly upgrade cycle would be a good
-way to keep up-to-date.  
+There are two aspects to maintaining a *TWEED* installation.  Firstly, *TWEED*
+itself is updated by downloading the latest files from the online repository.
+The configuration files contain information regarding packages added or
+removed, plus information on new versions and dependencies.  Secondly, the
+package managers have their own update procedures for the files that they
+control.  In the case of GNU Guix and Nix the procedures reference online
+package definitions.  In the case of HashDist the procedure references the
+local HashStack repository.
+
+There are two options for updating *TWEED* itself.  The latest tagged version
+may be downlaoded and unpacked, creating a new installation directory.
+Alternatively, if the installation is managed by *git*, the latest development
+version may be obtained by pulling the files directly from the repository.
+To use this method, simply navigate to the original installation directory and
+enter the command:
+
+	$ git pull
+
+The *TWEED* applications may then upgraded by updating the respective package
+managers.  The update procedures install the new application versions plus any
+new versions of dependencies.  A suitable update frequency can be determined by
+keeping a watch on application releases.  If there are approximately ten
+version releases per year in total, for example, then a monthly upgrade cycle
+would keep the installation up-to-date.
 
 All three package managers use a hash value as part of the pathname for an
 application.  Since all versions of an application have a different hash value
@@ -19,12 +37,11 @@ there is no conflict between older and newer versions.  Older versions are
 retained in the store by default.  It is possible to immediately switch to any
 version that has previously been installed.
 
-Each of the three package managers has its own update procedure.  To upgrade
-any given application it is only necessary to update one package manager.
-Sometimes an application has not been upgraded but some of its dependencies
-have been.  It is up to the user to decide whether or not to update the package
-manager in this case.  It is often acceptable to skip the dependency updates
-and wait for an upgrade to the application itself.
+To upgrade any given application it is only necessary to update one package
+manager.  Sometimes an application has not been upgraded but some of its
+dependencies have been.  It is up to the user to decide whether or not to
+update the package manager in this case.  It is often acceptable to skip the
+dependency updates and wait for an upgrade to the application itself.
 
 The update procedures are outlined below.  Each package manager also offers a
 way to delete unused files.  This is termed *garbage collection*.
@@ -86,6 +103,13 @@ installation process.  First, move to the HashStack directory and delete the
 
 	$ rm default
 
+If the configuration file, ``tweed.hashdist.yaml``, has been updated then it is
+necessary to delete the ``default.yaml`` file as well and replace it with the
+new version:
+
+	$ rm default.yaml
+	$ cp /path/to/tweed/installation/tweed.hashdist.yaml default.yaml
+
 Then, for a system with M cores available for the build process, run the
 command:
 
@@ -93,7 +117,9 @@ command:
 
 followed by:
 
-	$ sh tweed.hashdist.post-install
+	$ cd /path/to/tweed/installation
+	$ HASHSTACK_DIR=/path/to/hashstack/repository \
+		sh tweed.hashdist.post-install
 
 HashDist deletes previous application versions and removes unused files in one
 command: