Documentation updates, create upgrade document.

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

diff --git a/doc/create.rst b/doc/create.rst
index 1e4e88dee959145ff470c27f12d2c81f4283f7ee..cce7047929bfa423034e3cc740184445a126d00d 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
 
@@ -150,6 +150,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
 
@@ -362,16 +363,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 +565,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
 ---------------
 

diff --git a/doc/index.rst b/doc/index.rst
index fbc5b0c6550e793d7e7e94b118021c7366e10f2d..46d719c9b565f45e74b0e397724019a16ae726db 100644 (file)
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -54,8 +54,9 @@ Table of Contents
 .. toctree::
     :maxdepth: 1
 
-    testing
     create
+    upgrade
+    testing
     glossary
 
 Modules

diff --git a/doc/upgrade.rst b/doc/upgrade.rst
new file mode 100644 (file)
index 0000000..2acbca3
--- /dev/null
+++ b/doc/upgrade.rst
@@ -0,0 +1,60 @@
+Preparing an upgrade
+====================
+
+:Author: Edward Z. Yang <ezyang@mit.edu>
+
+Wizard is designed to make pushing upgrades as painless as possible.
+In the best case scenario, adding a new version to a Wizard repository
+is as simple as running a few commands.  Even when upstream makes
+backwards incompatible changes, or some of your patches conflict with
+other changes, Wizard aims to make resolving these changes tractable.
+
+This document is divided into two sections: first, the basic procedure,
+and then troubleshooting tips for recalcitrant upgrades.
+
+Summary
+-------
+
+``$VERSION`` is a version number i.e. ``1.2.4``,
+``$APPLICATION`` is the official application name i.e. ``MediaWiki``, and
+``$APP`` is our internal name i.e. ``mediawiki``.  The key thing to note
+is that we use ``wizard prepare-pristine`` in order to simulate the
+upstream upgrade, and then we piggy back off of Git's merge machinery
+to do everything else.
+
+First you prepare the pristine copy:
+
+.. code-block:: sh
+
+    git checkout pristine
+    wizard prepare-pristine $VERSION
+    git commit -asm "$APPLICATION $VERSION"
+    git tag $APP-$VERSION
+
+Next, you merge those changes to the scriptsified ``master`` copy:
+
+.. code-block:: sh
+
+    git checkout master
+    git merge pristine --no-commit
+    # resolve conflicts
+    git commit -asm "$APPLICATION $VERSION-scripts"
+
+Then, on a scripts server with Wizard pointed at the latest version, run:
+
+.. code-block:: sh
+
+    cd tests
+    env WIZARD_NO_COMMIT=1 ./test-install-$APP.sh
+    cd testdir_install_$APP_head
+    wizard prepare-config
+
+Manually restore any custom changes we may have made to the configuration
+file, make sure that no upstream changes broke our regular expressions
+for matching.  Then amend your commit and push back:
+
+.. code-block:: sh
+
+    git commit --amend -a
+    git push --force
+

diff --git a/wizard/command/install.py b/wizard/command/install.py
index fb2f085f378399f34de4f75b281f9caacc2d736f..87af9866b49bdad53fec64132498b0a1760d8038 100644 (file)
--- a/wizard/command/install.py
+++ b/wizard/command/install.py
@@ -58,7 +58,7 @@ def configure_parser(parser, baton):
     parser.add_option("--non-interactive", dest="non_interactive", action="store_true",
             default=False, help="Force program to be non-interactive and use SETUPARGS.  Use --help with APP to find argument names.")
     parser.add_option("--no-commit", dest="no_commit", action="store_true",
-            default=False, help="Do not generate an 'installation commit' after configuring the application.")
+            default=command.boolish(os.getenv("WIZARD_NO_COMMIT")), help="Do not generate an 'installation commit' after configuring the application. Envvar is WIZARD_NO_COMMIT")
     baton.push(parser, "srv_path")
 
 def parse_args(argv, baton):