Handle Wordpress random keys correctly on install and upgrade.

[wizard.git] / doc / create.rst

diff --git a/doc/create.rst b/doc/create.rst
index 8ff20132adf14549d4e8c3bf2833d4b9adf7eade..02953831665c25df803003a7737a6334c1916e83 100644 (file)
--- a/doc/create.rst
+++ b/doc/create.rst
@@ -79,9 +79,9 @@ add is the :term:`pristine` branch, which contains verbatim the code from upstre
     folder we store this information in: :file:`/mit/scripts/sec-tools/store/versions`.
 
 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`::
+should use the latest version.  Try running the following commands::
 
+    cd "$WIZARD/srv/wordpress"
     wizard prepare-pristine wordpress-2.0.2
 
 You should get an error complaining about :meth:`wizard.app.Application.download`
@@ -166,16 +166,29 @@ Installation
 ------------
 
 We now need to make it possible for a user to install the application.
-Most web applications have a number of web scripts for generating a
-configuration file, so creating the install script involves:
+The :meth:`~wizard.install.Application.install` method should take the
+application from a just cloned working copy into a fully functioning web
+application with configuration and a working database, etc.  Most web
+applications have a number of web scripts for generating a configuration
+file, so creating the install script tend to involve:
 
-    1. Determining what input values you will need from the user, such
+
+    1. Deleting any placeholder files that were in the repository (there
+       aren't any now, but there will be soon.)
+
+    2. Determining what input values you will need from the user, such
        as a title for the new application or database credentials; more
        on this shortly.
 
-    2. Determining what POST values need to be sent to what URLs.
-       Since you're converting a repository, this job is even simpler: you just
-       need to port the Perl script that was originally used into Python.
+    3. Determining what POST values need to be sent to what URLs or to
+       what shell scripts (these are the install scripts the application
+       may have supplied to you.)
+
+.. supplement:: Conversions
+
+    Since you're converting a repository, this job is even simpler: you
+    just need to port the Perl script that was originally used into
+    Python.
 
 There's an in-depth explanation of named input values in
 :mod:`wizard.install`.  The short version is that your application
@@ -216,11 +229,6 @@ Some tips and tricks for writing :meth:`wizard.app.Application.install`:
       consequently be queried.  For convenience, we've bound metadata
       to the connection, you can perform implicit execution.
 
-.. todo::
-
-    Our installer needs to also parametrize :file:`php.ini`, which we haven't
-    done yet.
-
 To test if your installation function works, it's probably convenient to
 create a test script in :file:`tests`; :file:`tests/test-install-wordpress.sh`
 in the case of Wordpress.  It will look something like::
@@ -342,6 +350,8 @@ we made:
         # ...
         parametrized_files = ['wp-config.php'] + php.parametrized_files
 
+.. _seed:
+
 And finally, we have :attr:`~wizard.app.Application.extractors` and
 :attr:`~wizard.app.Application.substitutions`.  At the bare metal, these
 are simply dictionaries of variable names to functions: when you call the
@@ -442,6 +452,11 @@ commit with these changes and force them back into the public repository::
     git commit --amend -a
     git push --force
 
+You should test again if your install script works; it probably doesn't,
+since you now have a configuration file hanging around.  Use
+:func:`wizard.util.soft_unlink` to remove the file at the very beginning
+of the install process.
+
 Ending ceremonies
 -----------------