doc/upgrade.rst

   1 Preparing an upgrade
   2 ====================
   3
   4 :Author: Edward Z. Yang <ezyang@mit.edu>
   5
   6 Wizard is designed to make pushing upgrades as painless as possible.
   7 In the best case scenario, adding a new version to a Wizard repository
   8 is as simple as running a few commands.  Even when upstream makes
   9 backwards incompatible changes, or some of your patches conflict with
  10 other changes, Wizard aims to make resolving these changes tractable.
  11
  12 This document is divided into two sections: first, the basic procedure,
  13 and then troubleshooting tips for recalcitrant upgrades.
  14
  15 Summary
  16 -------
  17
  18 ``$VERSION`` is a version number i.e. ``1.2.4``,
  19 ``$APPLICATION`` is the official application name i.e. ``MediaWiki``, and
  20 ``$APP`` is our internal name i.e. ``mediawiki``.  The key thing to note
  21 is that we use ``wizard prepare-pristine`` in order to simulate the
  22 upstream upgrade, and then we piggy back off of Git's merge machinery
  23 to do everything else.
  24
  25 First you prepare the pristine copy:
  26
  27 .. code-block:: sh
  28
  29     git checkout pristine
  30     wizard prepare-pristine $VERSION
  31     git commit -asm "$APPLICATION $VERSION"
  32     git tag $APP-$VERSION
  33
  34 Next, you merge those changes to the scriptsified ``master`` copy:
  35
  36 .. code-block:: sh
  37
  38     git checkout master
  39     git merge pristine --no-commit
  40     # resolve conflicts
  41     git commit -asm "$APPLICATION $VERSION-scripts"
  42
  43 Then, on a scripts server with Wizard pointed at the latest version, run:
  44
  45 .. code-block:: sh
  46
  47     cd tests
  48     env WIZARD_NO_COMMIT=1 ./test-install-$APP.sh
  49     cd testdir_install_$APP_head
  50     wizard prepare-config
  51
  52 Manually restore any custom changes we may have made to the configuration
  53 file, make sure that no upstream changes broke our regular expressions
  54 for matching.  Then amend your commit and push back:
  55
  56 .. code-block:: sh
  57
  58     git commit --amend -a
  59     git push --force
  60