Handle Wordpress random keys correctly on install and upgrade.

[wizard.git] / doc / upgrade.rst

diff --git a/doc/upgrade.rst b/doc/upgrade.rst
index 0c044aaaf2346aaf34f7aac3986ef46106c1aeea..259577d0fcb885b762b78f3b508e9409a37408e4 100644 (file)
--- a/doc/upgrade.rst
+++ b/doc/upgrade.rst
@@ -112,6 +112,12 @@ Finally, :meth:`~wizard.app.Application.upgrade` actually performs an upgrade,
 and will most frequently call a shell script or fetches a web page that will
 perform a schema upgrade.
 
+.. note::
+
+    When migrating an old-style autoinstall, it is neither expected nor
+    required for upgrade scripts for the intervening versions to be
+    created.
+
 Troubleshooting
 ---------------
 
@@ -133,3 +139,103 @@ the files to the pristine version::
 And then apply the patch.  If the patch is complicated, you may get
 warnings about hunks already being applied; you can ignore those warnings
 (don't assume ``-R``!)
+
+Going retro
+-----------
+
+Under certain circumstances, you may need to splice in older versions
+of the application into your history.  Do not rebase: you should never
+rebase published history.  Instead, use the following procedure:
+
+Identify the version that, with regards to version numbering,
+directly precedes the version you'd like to add.  For example, if
+you have the following commit tree:
+
+.. digraph:: original_dag
+
+    node [shape=square]
+    subgraph cluster_master {
+        bs -> as
+        as [label="1.0-scripts"]
+        bs [label="2.0-scripts"]
+        label = "master"
+        color = white
+    }
+    subgraph cluster_pristine {
+        b -> a
+        a [label="1.0"]
+        b [label="2.0"]
+        label = "pristine"
+        color = white
+    }
+    bs -> b
+    as -> a
+
+And you are adding the 1.1 version, 1.0 and 1.0-scripts are the
+tags immediately preceding this version.  Create temporary
+branches (we'll name them ``tmaster`` and ``tpristine``) pointing
+to these tags::
+
+    git checkout -b tmaster
+    git reset --hard 1.0-scripts
+    git checkout -b tpristine
+    git reset --hard 1.0
+
+Find the committer date associated with the ``tmaster`` commit using ``git show tmaster``
+and note it somewhere::
+
+    DATE=`git show tmaster --pretty="format:%cd" | head -n1`
+
+Next, begin performing ordinary procedure for preparing the
+pristine copy.  There are two caveats:  you will need to use ``--force``
+to make ``wizard prepare-pristine`` not complain about not being on
+the ``pristine`` branch, and you will need to falsify the author
+and committer time on the commits to be the times we noted down
+previously::
+
+    # on the tpristine branch
+    wizard prepare-pristine $APP-$VERSION --force
+    env GIT_AUTHOR_DATE="$DATE" GIT_COMMITTER_DATE="$DATE" git commit -asm "$APPLICATION $VERSION"
+    git tag $APP-$VERSION
+
+.. note::
+
+    The date falsification is necessary to make Git prefer the
+    later version tag when a commit has this (newer) commit and
+    the most up-to-date version as merge parents.  By default
+    Git prefers the temporally closest commit.
+
+Next, merge the changes to the scriptsified ``tmaster`` (not ``master``!) copy,
+and falsify the dates as well::
+
+    git checkout tmaster
+    git merge tpristine --no-commit
+    # resolve conflicts
+    env GIT_AUTHOR_DATE="$DATE" GIT_COMMITTER_DATE="$DATE" git commit -asm "$APPLICATION $VERSION-scripts"
+    git tag $APP-$VERSION-scripts
+
+Note that we are creating a tag, because otherwise there is not an easy way
+to refer to this non-HEAD tag.  On a scripts server with Wizard pointed at the
+latest version, run::
+
+    cd tests
+    env WIZARD_NO_COMMIT=1 ./$APP-install-test.sh $VERSION
+    cd testdir_install_$APP_$VERSION
+    wizard prepare-config
+
+Note that ``$VERSION`` is specified explicitly.  If there are changes,
+manually restore any custom changes we may have made, then amend your commit and
+push back::
+
+    # you probably lost your environment variable
+    DATE=`git show HEAD --pretty="format:%ad" | head -n1`
+    env GIT_AUTHOR_DATE="$DATE" GIT_COMMITTER_DATE="$DATE" git commit --amend -a
+    git tag -d $APP-$VERSION-scripts
+    git tag $APP-$VERSION-scripts
+    git push --force --tags
+
+And on your now invalid version, grab the new version::
+
+    git fetch --tags --force $REMOTE
+
+Note that there is no need to reset the master branch, which hasn't changed.