Setup the rest to use conversion supplements.

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

diff --git a/doc/_static/wizard.css b/doc/_static/wizard.css
index 2ca3a57e86dcd4b800376b815c5b8a97f7c38e63..1c67557a78265d4b68a3f5b7fedac3e8a1e06bcb 100644 (file)
--- a/doc/_static/wizard.css
+++ b/doc/_static/wizard.css
@@ -1,6 +1,18 @@
 @import 'default.css';
 
 .admonition-for-conversions {
-    background-color: #EDE5D2;
+    background: #EDE5D2;
     border: 1px solid #B7937F;
 }
+
+.admonition-for-conversions tt {
+    background: #DFD3B5;
+}
+
+.warning tt {
+    background: #EFC2C2;
+}
+
+.note tt {
+    background: #D6D6D6;
+}

diff --git a/doc/create.rst b/doc/create.rst
index cea861ed9c102a66eb6b193a152d8bbad8b69aee..a3e7cbd9c100d62dd228cf563fa1282f19a3a6c1 100644 (file)
--- a/doc/create.rst
+++ b/doc/create.rst
@@ -1,6 +1,8 @@
 Creating a repository
 =====================
 
+:Authors: Edward Z. Yang <ezyang@mit.edu>
+
 .. highlight:: sh
 
 Adding Wizard support for a web application requires some glue code
@@ -17,23 +19,21 @@ installing an application--upgrades and backups are not described here.
 
 .. supplement:: Conversions
 
-    One of Wizard's goals is to replace the previous autoinstaller infrastructure.
-    These boxes will explain extra steps that you must perform in order to carry
-    out a conversion of old-style autoinstalls to a Wizard autoinstall.
-    In brief, 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).  Performing a conversion means that we will
-    recreate these changes in our Wizard autoinstall, and you will start you
-    repository with the *earliest* version of the application extant on our
-    servers.
+    One of Wizard's goals is to replace the previous autoinstaller
+    infrastructure.  These boxes will explain extra steps that you must perform
+    in order to carry out a conversion of old-style autoinstalls to a Wizard
+    autoinstall.  In brief, 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).
+    Performing a conversion means that we will recreate these changes in our
+    Wizard autoinstall, and you will start you repository with the *earliest*
+    version of the application extant on our servers.
 
 Setup
 -----
 
-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
+Probably the easiest way to do development is entirely on :term:`AFS`, 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 order
 to be able to run the test scripts in the tests directory, this
@@ -41,17 +41,31 @@ is preferably in :file:`web_scripts`. In that
 case, setup is as simple as::
 
     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 /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
-scripts servers, but before your changes get incorporated into
-canonical upstream.  Git doesn't exactly make this easy, but you
-can follow this recipe::
+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``.
+
+.. warning::
+
+    Other users will not be able to access your source code.  If you
+    change the access control to allow ``system:anyuser`` to read your
+    source code (in case you want to let other people test your
+    code), do *not* give access to the :file:`tests` directory,
+    which may contain sensitive data.
+
+Advanced setup
+''''''''''''''
 
-    git clone /mit/scripts/git/wizard.git ~/wizard
+These instructions are for if you'd like to be able to develop offline and are
+on ``scripts-root``.  Wizard will mostly work on your local machine, but you
+won't be able to do all development offline; some steps in the development
+process must be performed on scripts servers.  Thus, the difficult part is
+marshalling commits from one repository to another. Git doesn't exactly make
+this easy, but you can follow this recipe::
+
+    git clone ssh://scripts@scripts.mit.edu/mit/scripts/git/wizard.git ~/wizard
     cd /mit/$USER
     mkdir wizard.git
     cd wizard.git
@@ -61,6 +75,9 @@ can follow this recipe::
     git push -f afs master
     git clone /mit/$USER/wizard.git /mit/$USER/wizard
 
+We create a bare repository :file:`/mit/$USER/wizard.git` that you can push and
+pull from, and then setup an alternate remote ``afs`` on your offline copy.
+
 And then you can perform updates from your local copy with::
 
     git push afs master
@@ -74,14 +91,16 @@ changes back to the canonical repository (please don't give ``not-backward.mit.e
 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``.
+.. warning::
+
+    These instructions are not well tested.  Let me know if you run into
+    any difficulties.
 
 Pristine
 --------
 
-This is a tutorial centered around migrating `Wordpress <http://wordpress.org/>`_
-into our Git repository.  For the sake of demonstration,
+This is a tutorial centered around creating a `Wordpress <http://wordpress.org/>`_
+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::
 
@@ -91,7 +110,7 @@ The repository then doesn't exist, we should create it::
     git init
 
 We also have to create a module for the application, so we
-create ``$WIZARD/wizard/app/wordpress.py`` and fill it in with a bare bones template:
+create :file:`$WIZARD/wizard/app/wordpress.py` and fill it in with a bare bones template:
 
 .. code-block:: python
 
@@ -107,16 +126,21 @@ create ``$WIZARD/wizard/app/wordpress.py`` and fill it in with a bare bones temp
 
 Now we are ready to put some code in our repository: the first thing we will
 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::
 
-    wizard summary version APP
+.. supplement:: Conversions
+
+    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::
+
+        wizard summary version APP
 
-You'll need to be in the ``scripts-team`` list in order to access the data to
-run this command.
+    You'll need to be in the ``scripts-team`` list to have access rights to the
+    folder we store this information in: :file:`/mit/scripts/sec-tools/store/versions`.
 
-Try running the following command in :file:`$WIZARD/srv/wordpress`::
+For the purposes of demonstration, we'll use Wordpress 2.0.2; in reality you
+should use the latest version.  Try running the following command in
+:file:`$WIZARD/srv/wordpress`::
 
     wizard prepare-pristine wordpress-2.0.2
 
@@ -154,6 +178,11 @@ can also create a pristine branch::
 
     git branch pristine
 
+.. todo::
+
+    The following text and graph should be put in a more general overview of
+    the topology of Wizard git repositories.
+
 From the point of view of the pristine branch pointer, history should be a
 straight-forward progression of versions.  Once you have more versions,
 it will look something like:
@@ -182,6 +211,11 @@ work correctly.  Due to the way Git's merge algorithm works, the closer we are
 able to reconstruct a version of the application that was actually used, the
 better off we will be when we try to subsequently upgrade those applications.
 
+.. todo::
+
+    The following text and graph should be put in a more general overview of
+    the topology of Wizard git repositories.
+
 To give you an idea of what the Git history graph will look like when we
 are done, here is the graph from before, but augmented with the scripts versions:
 
@@ -216,11 +250,13 @@ First things first: verify that we are on the master branch::
 
     git checkout master
 
-Check for pre-existing patches in the old application directory,
-:file:`/mit/scripts/deploy/wordpress-2.0.2` in the case of Wordpress,
-and apply them::
+.. supplement:: Conversions
+
+    Check for pre-existing patches in the old application directory,
+    :file:`/mit/scripts/deploy/wordpress-2.0.2` in the case of Wordpress,
+    and apply them::
 
-    patch -n0 < /mit/scripts/deploy/wordpress-2.0.2/wordpress.patch
+        patch -n0 < /mit/scripts/deploy/wordpress-2.0.2/wordpress.patch
 
 Then, run the following command to setup a :file:`.scripts` directory::
 

diff --git a/doc/index.rst b/doc/index.rst
index 72afe43546af415d6b1dc0bfa0ba0037f1ffec09..fbc5b0c6550e793d7e7e94b118021c7366e10f2d 100644 (file)
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -52,6 +52,7 @@ Table of Contents
 -----------------
 
 .. toctree::
+    :maxdepth: 1
 
     testing
     create