Revise existing repository conversion instructions.

Signed-off-by: Edward Z. Yang <ezyang@mit.edu>

diff --git a/doc/glossary.rst b/doc/glossary.rst
index 7012b8336c05358239052855963020f3a1d800c4..c2e0c8d8f3fe59e7bd0a7c4c6979479f4b3a2569 100644 (file)
--- a/doc/glossary.rst
+++ b/doc/glossary.rst
@@ -3,6 +3,15 @@ Glossary
 
 .. glossary::
 
+    AFS
+        A networked filesystem that is widely deployed at MIT and CMU.
+        ``scripts.mit.edu`` serves files from AFS.
+
+    pristine
+        The branch containing clean, unmodified copies of application code straight
+        from upstream, though possibly with blank :file:`.preserve-dir` files
+        added to empty directories to preserve their existence in Git.
+
     versions store
         The directory residing in ``/mit/scripts/sec-tools/store/versions``.
         It is generated by :command:`parallel-find.pl` (found at

diff --git a/doc/repository-conversion.rst b/doc/repository-conversion.rst
index 5c529de45a09451c59501481c7c6a1d4bb908264..bb5c5b1dbaf7b555caedee818e9187f8964f82df 100644 (file)
--- a/doc/repository-conversion.rst
+++ b/doc/repository-conversion.rst
@@ -1,19 +1,17 @@
 Repository conversion
 =====================
 
-Pre-wizard autoinstalls live in::
+One of Wizard's goals is to replace the previous autoinstaller infrastructure.
+Pre-wizard autoinstalls live in :file:`/mit/scripts/deploy` and consist of a
+tarball from upstream, possibly a scripts patch, and possibly some post-install
+munging (such as the creation of a :file:`php.ini` file and appropriate
+symlinks).
 
-    /mit/scripts/deploy     # production
-    /mit/scripts/deploydev  # development
-
-And consist of a tarball from upstream, possibly a scripts
-patch, and possibly some post-install munging (such as the creation
-of a php.ini file and appropriate symlinks).
-
-Conversion to Wizard involves placing pristine versions of the source
+Conversion to use Wizard involves placing :term:`pristine` versions of the source
 code (from the upstream tarballs) and appropriately patched scripts
 versions into a Git repository, as well as writing a :mod:`wizard.app`
-module for the application that defines common operations.
+module for the application that implements application specific logic, such
+as how to install, upgrade or backup the installation.
 
 Here is a tutorial for performing a conversion, using Wordpress as
 an example.
@@ -23,17 +21,19 @@ Setup
 
 .. highlight:: sh
 
-Probably the easiest way to do development is entirely on AFS:  all
+Probably the easiest way to do development is entirely on :term:`AFS`:  all
 of your source code should live in publically readable (i.e.
-system:anyuser as read permissions) directories, so that if you
+``system:anyuser`` as read permissions) directories, so that if you
 SSH into a scripts server to perform testing, you will be able
-to invoke your tools and read your development repository.  In that
+to invoke your tools and read your development repository.  In order
+to be able to run the test scripts in the tests directory, this
+is preferably in :file:`web_scripts`. In that
 case, setup is as simple as::
 
-    git clone /mit/scripts/git/wizard.git /mit/$USER/wizard
-    athrun consult fsr /mit/$USER/wizard system:anyuser read
+    git clone /mit/scripts/git/wizard.git /mit/$USER/web_scripts/wizard
+    athrun consult fsr /mit/$USER/web_scripts/wizard system:anyuser read
     # for any application you're going to do development on, also:
-    git clone /mit/scripts/git/autoinstalls/$APP.git ~/wizard/srv/$APP
+    git clone /mit/scripts/git/autoinstalls/$APP.git /mit/$USER/web_scripts/wizard/srv/$APP
 
 If you'd like to be able to develop offline, just note that you will
 have to push your changes to AFS once you start doing testing on
@@ -57,11 +57,12 @@ And then you can perform updates from your local copy with::
     cd /mit/$USER/wizard
     git pull
 
-If ``/mit/$USER/wizard.git`` has write permissions for
+If :file:`/mit/$USER/wizard.git` has write permissions for
 ``system:scripts-security-upd``, this is especially useful if you were hacking
 on a copy living on ``not-backward.mit.edu``, and now need to transfer the
 changes back to the canonical repository (please don't give ``not-backward.mit.edu``
-your root tickets!)
+your root tickets!)  You can also setup a wizard directory similar to the
+first set of directions for on-server testing.
 
 From this point on, we will assume you are doing development from an AFS directory
 named ``$WIZARD``; note that application repositories live in ``$WIZARD/srv``.
@@ -71,8 +72,10 @@ Pristine
 
 .. highlight:: sh
 
-This is a tutorial for migrating Wordpress into our Git repository.  As such
-a repository doesn't exist, we should create it::
+This is a tutorial centered around migrating `Wordpress <http://wordpress.org/>`_
+into our Git repository.  For the sake of demonstration,
+we shall assume that this repository hasn't been created yet.
+The repository then doesn't exist, we should create it::
 
     cd "$WIZARD/srv"
     mkdir wordpress
@@ -91,7 +94,7 @@ create ``$WIZARD/wizard/app/wordpress.py`` and fill it in with a bare bones temp
 .. highlight:: sh
 
 Now we are ready to put some code in our repository: the first thing we will
-add is the "pristine branch", which contains verbatim the code from upstream.
+add is the :term:`pristine` branch, which contains verbatim the code from upstream.
 If we were starting a new autoinstaller, we'd pop off and use the latest version,
 but since we're dealing with legacy we want to start our repository history
 with the **oldest** version still extant on our servers.  To find this out run::
@@ -101,10 +104,10 @@ with the **oldest** version still extant on our servers.  To find this out run::
 You'll need to be in the ``scripts-team`` list in order to access the data to
 run this command.
 
-Try running the following command in "$WIZARD/srv/wordpress"::
+Try running the following command in :file:`$WIZARD/srv/wordpress`::
 
     wizard prepare-pristine wordpress-2.0.2
 
-You should get an error complaining about ``download()`` not being implemented yet.
+You should get an error complaining about :func:`wizard.app.Application.download` not being implemented yet.
 
 (to be continued)