Fix semantics for date falsification to use scripts.

[wizard.git] / doc / upgrade.rst

diff --git a/doc/upgrade.rst b/doc/upgrade.rst
index 52787336f2d3358471326843657b2651ab699461..be9c2363e425fc147c04185563240048cb124b58 100644 (file)
--- a/doc/upgrade.rst
+++ b/doc/upgrade.rst
@@ -34,7 +34,6 @@ Next, you merge those changes to the scriptsified ``master`` copy::
     git merge pristine --no-commit
     # resolve conflicts
     git commit -asm "$APPLICATION $VERSION-scripts"
-    git tag $APP-$VERSION
 
 .. note::
 
@@ -48,12 +47,14 @@ Then, on a scripts server with Wizard pointed at the latest version, run::
     cd testdir_install_$APP_head
     wizard prepare-config
 
-Manually restore any custom changes we may have made to the configuration
+With any luck, there will be no differences; if there are
+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::
 
     git commit --amend -a
     git tag $APP-$VERSION-scripts
+    git push --force
     git push --force --tags
 
 On any other copies that have the older commit, run the following commands
@@ -132,3 +133,104 @@ 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 --format="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 --format="format:%cd" | 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
+    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.