README

   1 Wizard is the new autoinstaller management system for
   2 scripts.mit.edu.  It resides on not-backward.mit.edu at:
   3
   4     /wizard
   5
   6 Developers, read on:
   7
   8 == Compatibility ==
   9
  10 This is Python 2.6 only!
  11
  12 == Module overview ==
  13
  14 - deploy: object model for autoinstall deployments, applications
  15     and versions
  16
  17 - shell: subprocess wrapper that does logging, error handling
  18     and asynchronous processing
  19
  20 - sset: "serialized set", use in a mass* command for tracking
  21     what installs have already been seen and successfully processed
  22
  23 - util: miscellaneous utility functions, right now mostly one-off
  24     parsing and convenience wrappers
  25
  26 == 'command' package ==
  27
  28 To add a new command to wizard, you need to touch the following
  29 locations:
  30
  31 - bin/wizard
  32     Add a line describing your command in the helpstring
  33
  34 - wizard/command/__init__.py
  35     Add the line "import commandname"
  36
  37 - wizard/command/commandname.py
  38     Implement your command there as main(). Copy the function
  39     signature and scaffolding from another file; it's non-trivial
  40
  41 As a command file, you're expected to have a main() and parse_args()
  42 function.  Try to keep main() one to two page function that can
  43 be browsed for a descriptive overview of what the command does
  44 internally.  Use helper functions liberally.  Place all error classes
  45 at the bottom.
  46
  47 == 'app' package ==
  48
  49 There is a certain amount of application specific code that
  50 needs to be written for each autoinstaller.  These go here.
  51
  52 == Notes when fiddling with application repositories ==
  53
  54 - 'git rebase -p -i' is your friend.  Use it to rewrite history!
  55
  56 - The obvious scripts specific change that a new repository
  57   will have are the patches, but you should also check the
  58   autoinstall scripts if they do anything special.  In particular:
  59
  60     - If it's a PHP application, it's probably inserting a php.ini
  61       file and creating symlinks to it.  Be sure to replace the
  62       appropriate values with placeholders WIZARD_SESSIONNAME
  63       and WIZARD_TMPDIR
  64
  65     - You will probably need to generate relevant configuration
  66       files for each version
  67
  68 == Design decisions ==
  69
  70 - A mass tool will plow ahead even if the subcommand throws
  71   Wizard errors.  Normal errors will cause us to halt
  72   completely.  If the error that occured is within the realm
  73   of possibly, and should be dealt with by manual intervention
  74   (or even possibly a code change), and would not cause harm
  75   if we continued going, we will keep going, and let the maintainer
  76   deal later on with the errors en masse.
  77
  78 - We use the Google Python style guide.  See:
  79     http://code.google.com/p/soc/wiki/PythonStyleGuide