Add anatomy of a repository docs.

[wizard.git] / doc / create.rst

diff --git a/doc/create.rst b/doc/create.rst
index 1e4e88dee959145ff470c27f12d2c81f4283f7ee..c040f5513c7849da2f9abd8a2653dcb28df55f2c 100644 (file)
--- a/doc/create.rst
+++ b/doc/create.rst
@@ -1,7 +1,7 @@
 Creating a repository
 =====================
 
-:Authors: Edward Z. Yang <ezyang@mit.edu>
+:Author: Edward Z. Yang <ezyang@mit.edu>
 
 .. highlight:: sh
 
@@ -117,6 +117,7 @@ create :file:`$WIZARD/wizard/app/wordpress.py` and fill it in with a bare bones
     import os
     import re
     import logging
+    import distutils
 
     from wizard import app, install, resolve, sql, util
     from wizard.app import php
@@ -150,6 +151,7 @@ not being implemented yet. Let's fix that:
 .. code-block:: python
 
     class Application(app.Application):
+        # ...
         def download(self, version):
             return "http://wordpress.org/wordpress-%s.tar.gz" % version
 
@@ -178,29 +180,6 @@ 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:
-
-.. digraph:: pristine_dag
-
-    rankdir=LR
-    node [shape=square]
-    subgraph cluster_pristine {
-        a -> b -> c
-        a [label="1.0"]
-        b [label="1.1"]
-        c [label="2.0"]
-        label = "pristine"
-        color = white
-        labeljust = r
-    }
-
 Scriptsify
 ----------
 
@@ -211,41 +190,6 @@ 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:
-
-.. digraph:: master_dag
-
-    rankdir=LR
-    node [shape=square]
-    subgraph cluster_pristine {
-        a -> b -> c
-        a [label="1.0"]
-        b [label="1.1"]
-        c [label="2.0"]
-        label = "pristine"
-        color = white
-        labeljust = r
-    }
-    subgraph cluster_master {
-        as -> bs -> cs
-        as [label="1.0-scripts"]
-        bs [label="1.1-scripts"]
-        cs [label="2.0-scripts"]
-        label = "master"
-        color = white
-        labeljust = r
-    }
-    a -> as
-    b -> bs
-    c -> cs
-    a []
-
 First things first: verify that we are on the master branch::
 
     git checkout master
@@ -362,16 +306,16 @@ the scriptsified versions would contain generic copies of the configuration
 files.  You're going to generate this generic copy now and in doing so,
 overload your previous scripts commit.   Because some installers
 exhibit different behavior depending on server configuration, you should run
-the installation on a Scripts server::
+the installation on a Scripts server.  You can do this manually or use
+the test script you created::
 
-    wizard install wordpress --no-commit
+    env WIZARD_NO_COMMIT=1 ./test-install-wordpress.sh
 
-The installer will interactively prompt you for some values, and then conclude
-the install.  ``--no-commit`` prevents the installer from generating a Git
-commit after the install, and will make it easier for us to propagate the
-change back to the parent repository.
+:envvar:`WIZARD_NO_COMMIT` (command line equivalent to ``--no-commit``)
+prevents the installer from generating a Git commit after the install, and will
+make it easier for us to propagate the change back to the parent repository.
 
-Look at the changes the installer made::
+Change into the generated directory and look at the changes the installer made::
 
     git status
 
@@ -564,6 +508,31 @@ commit as ``appname-x.y.z-scripts``, or in this specific case::
     git tag wordpress-2.0.4-scripts
     git push --tags
 
+Summary
+-------
+
+Here is short version for quick reference:
+
+#. Create the new repository and new module,
+#. Implement :meth:`~wizard.app.Application.download`,
+#. *For Conversions:* Find the oldest extant version with ``wizard summary version $APP``,
+#. Run ``wizard prepare-pristine $VERSION``,
+#. Commit with ``-m "$APPLICATION $VERSION"`` and tag ``$APP-$VERSION``,
+#. Create ``pristine`` branch, but stay on ``master`` branch,
+#. *For Conversions:* Check for pre-existing patches, and apply them,
+#. Run ``wizard prepare-new``,
+#. *For PHP:* Copy in :file:`php.ini` file and run ``athrun scripts fix-php-ini``,
+#. Commit with ``-m "$APPLICATION $VERSION"``, but *don't* tag,
+#. Implement :data:`~wizard.app.Application.install_schema` and :meth:`~wizard.app.Application.install`,
+#. Create :file:`tests/test-install-$APP.sh`,
+#. On a scripts server, run ``wizard install $APP --no-commit`` and check changes with ``git status``,
+#. Implement :attr:`~wizard.app.Application.extractors`,
+   :attr:`~wizard.app.Application.substitutions`, :attr:`~wizard.app.Application.parametrized_files`,
+   :meth:`~wizard.app.Application.checkConfig` and :meth:`~wizard.app.Application.detectVersion`,
+#. Run ``wizard prepare-config``,
+#. Amend commit and push back, and finally
+#. Tag ``$APP-$VERSION-scripts``
+
 Further reading
 ---------------