doc/repository-conversion.rst

   1 Repository conversion
   2 =====================
   3
   4 One of Wizard's goals is to replace the previous autoinstaller infrastructure.
   5 Pre-wizard autoinstalls live in :file:`/mit/scripts/deploy` and consist of a
   6 tarball from upstream, possibly a scripts patch, and possibly some post-install
   7 munging (such as the creation of a :file:`php.ini` file and appropriate
   8 symlinks).
   9
  10 Conversion to use Wizard involves placing :term:`pristine` versions of the source
  11 code (from the upstream tarballs) and appropriately patched scripts
  12 versions into a Git repository, as well as writing a :mod:`wizard.app`
  13 module for the application that implements application specific logic, such
  14 as how to install, upgrade or backup the installation.
  15
  16 Here is a tutorial for performing a conversion, using Wordpress as
  17 an example.
  18
  19 Setup
  20 -----
  21
  22 .. highlight:: sh
  23
  24 Probably the easiest way to do development is entirely on :term:`AFS`:  all
  25 of your source code should live in publically readable (i.e.
  26 ``system:anyuser`` as read permissions) directories, so that if you
  27 SSH into a scripts server to perform testing, you will be able
  28 to invoke your tools and read your development repository.  In order
  29 to be able to run the test scripts in the tests directory, this
  30 is preferably in :file:`web_scripts`. In that
  31 case, setup is as simple as::
  32
  33     git clone /mit/scripts/git/wizard.git /mit/$USER/web_scripts/wizard
  34     athrun consult fsr /mit/$USER/web_scripts/wizard system:anyuser read
  35     # for any application you're going to do development on, also:
  36     git clone /mit/scripts/git/autoinstalls/$APP.git /mit/$USER/web_scripts/wizard/srv/$APP
  37
  38 If you'd like to be able to develop offline, just note that you will
  39 have to push your changes to AFS once you start doing testing on
  40 scripts servers, but before your changes get incorporated into
  41 canonical upstream.  Git doesn't exactly make this easy, but you
  42 can follow this recipe::
  43
  44     git clone /mit/scripts/git/wizard.git ~/wizard
  45     cd /mit/$USER
  46     mkdir wizard.git
  47     cd wizard.git
  48     git init --bare
  49     cd ~/wizard
  50     git remote add afs /mit/$USER/wizard.git
  51     git push -f afs master
  52     git clone /mit/$USER/wizard.git /mit/$USER/wizard
  53
  54 And then you can perform updates from your local copy with::
  55
  56     git push afs master
  57     cd /mit/$USER/wizard
  58     git pull
  59
  60 If :file:`/mit/$USER/wizard.git` has write permissions for
  61 ``system:scripts-security-upd``, this is especially useful if you were hacking
  62 on a copy living on ``not-backward.mit.edu``, and now need to transfer the
  63 changes back to the canonical repository (please don't give ``not-backward.mit.edu``
  64 your root tickets!)  You can also setup a wizard directory similar to the
  65 first set of directions for on-server testing.
  66
  67 From this point on, we will assume you are doing development from an AFS directory
  68 named ``$WIZARD``; note that application repositories live in ``$WIZARD/srv``.
  69
  70 Pristine
  71 --------
  72
  73 .. highlight:: sh
  74
  75 This is a tutorial centered around migrating `Wordpress <http://wordpress.org/>`_
  76 into our Git repository.  For the sake of demonstration,
  77 we shall assume that this repository hasn't been created yet.
  78 The repository then doesn't exist, we should create it::
  79
  80     cd "$WIZARD/srv"
  81     mkdir wordpress
  82     cd wordpress
  83     git init
  84
  85 .. highlight:: python
  86
  87 We also have to create a module for the application, so we
  88 create ``$WIZARD/wizard/app/wordpress.py`` and fill it in with a bare bones template::
  89
  90     from wizard import app
  91     class Application(app.Application):
  92         pass
  93
  94 .. highlight:: sh
  95
  96 Now we are ready to put some code in our repository: the first thing we will
  97 add is the :term:`pristine` branch, which contains verbatim the code from upstream.
  98 If we were starting a new autoinstaller, we'd pop off and use the latest version,
  99 but since we're dealing with legacy we want to start our repository history
 100 with the **oldest** version still extant on our servers.  To find this out run::
 101
 102     wizard summary version APP
 103
 104 You'll need to be in the ``scripts-team`` list in order to access the data to
 105 run this command.
 106
 107 Try running the following command in :file:`$WIZARD/srv/wordpress`::
 108
 109     wizard prepare-pristine wordpress-2.0.2
 110
 111 You should get an error complaining about :func:`wizard.app.Application.download` not being implemented yet.
 112
 113 (to be continued)