README

   1 Wizard is the new autoinstaller management system for
   2 scripts.mit.edu.  It resides in:
   3
   4     /mit/scripts/wizard
   5
   6 It runs out of the box with the binaries in bin/; try
   7 `bin/wizard help` for some ideas on what to do.
   8 Repositories for autoinstall applications should reside
   9 in srv/, but are not versioned here.
  10
  11 Developers, read on:
  12
  13 == Compatibility ==
  14
  15 This is Python 2.6 only!
  16
  17 == Module overview ==
  18
  19 - deploy: object model for autoinstall deployments, applications
  20     and versions
  21
  22 - shell: subprocess wrapper that does logging, error handling
  23     and asynchronous processing
  24
  25 - sset: "serialized set", use in a mass* command for tracking
  26     what installs have already been seen and successfully processed
  27
  28 - util: miscellaneous utility functions, right now mostly one-off
  29     parsing and convenience wrappers
  30
  31 == 'command' package ==
  32
  33 To add a new command to wizard, you need to touch the following
  34 locations:
  35
  36 - bin/wizard
  37     Add a line describing your command in the helpstring
  38
  39 - wizard/command/__init__.py
  40     Add the line "import commandname"
  41
  42 - wizard/command/commandname.py
  43     Implement your command there as main(). Copy the function
  44     signature and scaffolding from another file; it's non-trivial
  45
  46 As a command file, you're expected to have a main() and parse_args()
  47 function.  Try to keep main() one to two page function that can
  48 be browsed for a descriptive overview of what the command does
  49 internally.  Use helper functions liberally.  Place all error classes
  50 at the bottom.
  51
  52 == Design decisions ==
  53
  54 - A mass tool will plow ahead even if the subcommand throws
  55   Wizard errors.  Normal errors will cause us to halt
  56   completely.  If the error that occured is within the realm
  57   of possibly, and should be dealt with by manual intervention
  58   (or even possibly a code change), and would not cause harm
  59   if we continued going, we will keep going, and let the maintainer
  60   deal later on with the errors en masse.
  61
  62 - We use the Google Python style guide.  See:
  63     http://code.google.com/p/soc/wiki/PythonStyleGuide