doc/upgrade.rst

   1 Preparing an upgrade
   2 ====================
   3
   4 :Author: Edward Z. Yang <ezyang@mit.edu>
   5
   6 .. highlight:: sh
   7
   8 Wizard is designed to make pushing upgrades as painless as possible.
   9 In the best case scenario, adding a new version to a Wizard repository
  10 is as simple as running a few commands.  Even when upstream makes
  11 backwards incompatible changes, or some of your patches conflict with
  12 other changes, Wizard aims to make resolving these changes tractable.
  13
  14 Summary
  15 -------
  16
  17 ``$VERSION`` is a version number i.e. ``1.2.4``,
  18 ``$APPLICATION`` is the official application name i.e. ``MediaWiki``, and
  19 ``$APP`` is our internal name i.e. ``mediawiki``.  The key thing to note
  20 is that we use ``wizard prepare-pristine`` in order to simulate the
  21 upstream upgrade, and then we piggy back off of Git's merge machinery
  22 to do everything else.
  23
  24 First you prepare the pristine copy::
  25
  26     git checkout pristine
  27     wizard prepare-pristine $APP-$VERSION
  28     git commit -asm "$APPLICATION $VERSION"
  29     git tag $APP-$VERSION
  30
  31 Next, you merge those changes to the scriptsified ``master`` copy::
  32
  33     git checkout master
  34     git merge pristine --no-commit
  35     # resolve conflicts
  36     git commit -asm "$APPLICATION $VERSION-scripts"
  37
  38 .. note::
  39
  40     If you are creating a fix for a previous scripts version, you should
  41     bump the version to ``$VERSION-scripts2``.
  42
  43 Then, on a scripts server with Wizard pointed at the latest version, run::
  44
  45     cd tests
  46     env WIZARD_NO_COMMIT=1 ./test-install-$APP.sh
  47     cd testdir_install_$APP_head
  48     wizard prepare-config
  49
  50 With any luck, there will be no differences; if there are
  51 manually restore any custom changes we may have made to the configuration
  52 file, make sure that no upstream changes broke our regular expressions
  53 for matching.  Then amend your commit and push back::
  54
  55     git commit --amend -a
  56     git tag $APP-$VERSION-scripts
  57     git push --force
  58     git push --force --tags
  59
  60 On any other copies that have the older commit, run the following commands
  61 while on the ``master`` branch to grab the new version::
  62
  63     git fetch --tags $REMOTE
  64     git reset --hard $REMOTE/master
  65
  66 Be sure to verify that your commit is the correct one; you can check with
  67 ``git show``, which should show the changes you made when amending the
  68 commit.  Be especially careful to make sure you don't nuke any in
  69 configuration scripts changes.
  70
  71 Implementation
  72 --------------
  73
  74 If it is the first time you have pushed an upgrade for an application, you
  75 will have to write a few more methods in your :class:`wizard.app.Application`
  76 class:  :meth:`~wizard.app.Application.upgrade`, :meth:`~wizard.app.Application.checkWeb`,
  77 :meth:`~wizard.app.Application.backup` and :meth:`~wizard.app.Application.restore`.
  78 The latter three may not seem so useful for just pushing an upgrade, but are helpful
  79 for integrity checking installations post-upgrade, and rolling back if something
  80 went wrong.
  81
  82 :meth:`~wizard.app.Application.checkWeb` is a method that should check whether
  83 or not an application is running properly.  We use this to prevent us from trying
  84 to upgrade an install that is not publically accessible, or was broken from
  85 the very start, and we use it to automatically determine if our upgrade was
  86 successful or not.  A common and easy way to perform this check is to
  87 use the :meth:`~wizard.app.Application.checkWebPage` method, which, along
  88 with the parameters :meth:`~wizard.app.Application.checkWeb` accepts, accepts
  89 two more: ``page`` and ``output``, which correspond to the page to grab from
  90 the web and the output string to match for in this page,
  91
  92 .. warning::
  93
  94     We still haven't quite figured out a good combination of in-depth error checking
  95     and robustness against skin changes.  This section should be further developed
  96     with tips about this.
  97
  98 :meth:`~wizard.app.Application.backup` and :meth:`~wizard.app.Application.restore`
  99 perform backup and restoration of non-filesystem contents; the most common application
 100 is for the database.  :func:`wizard.app.backup_database` and :func:`wizard.app.restore_database`
 101 implement this common functionality, and for
 102 most application implementing these methods is as simple as:
 103
 104 .. code-block:: python
 105
 106     def backup(self, deployment, backup_dir, options):
 107         app.backup_database(backup_dir, deployment)
 108     def restore(self, deployment, backup_dir, options):
 109         app.restore_database(backup_dir, deployment)
 110
 111 Finally, :meth:`~wizard.app.Application.upgrade` actually performs an upgrade,
 112 and will most frequently call a shell script or fetches a web page that will
 113 perform a schema upgrade.
 114
 115 Troubleshooting
 116 ---------------
 117
 118 Merge failed
 119 ''''''''''''
 120
 121 When a merge fails, it's often good to refresh your memory about what
 122 particular patch was made to that file.  You can find out with::
 123
 124     git diff :1:$FILE :2:$FILE
 125
 126 If you are performing a repository conversion, a failed merge likely
 127 means that there is an updated patch lying around in
 128 :file:`/mit/scripts/deploy/$APP-$VERSION`.  You can then revert
 129 the files to the pristine version::
 130
 131     git checkout --theirs $FILE
 132
 133 And then apply the patch.  If the patch is complicated, you may get
 134 warnings about hunks already being applied; you can ignore those warnings
 135 (don't assume ``-R``!)