README

   1 Wizard is the new autoinstaller management system for
   2 scripts.mit.edu.  This is a developer oriented introduction,
   3 and will get placed in doc/ soon.
   4
   5
   6 Compatibility
   7 -------------
   8
   9 This is Python 2.6 only!
  10
  11
  12 The command package
  13 -------------------
  14
  15 To add a new command to wizard, you need to touch the following
  16 locations:
  17
  18 - bin/wizard
  19     Add a line describing your command in the helpstring
  20
  21 - wizard/command/command_name.py
  22     Implement your command there as main(). Copy the function
  23     signature and scaffolding from another file; it's non-trivial
  24     Underscores in the module-name are referenced using dashes.
  25
  26 As a command file, you're expected to have a main() and parse_args()
  27 function.  Try to keep main() one to two page function that can
  28 be browsed for a descriptive overview of what the command does
  29 internally.  Use helper functions to create self-documenting
  30 code.  Don't make helper functions for one-liners.  Place
  31 all error classes at the bottom.
  32
  33
  34 Notes for repository creation
  35 -----------------------------
  36
  37 See TODO for full instructions.
  38
  39 - You are not going to be able to doctor a perfect repository
  40   from scratch.
  41
  42     * If you have a simple change to a commit message, or
  43       something that you don't really need interactive control
  44       over (such as methodically rm'ing a file), git
  45       filter-branch is very superior.
  46
  47     * 'git rebase -p -i' can be used to rewrite history interactively.
  48       Doing this will nuke any manual merge resolution you
  49       may have done (which may be a lot), thus, I highly
  50       recommend that you enable rerere (rerere.enabled = true)
  51       so that Git can automatically merge things for you.
  52       If the merge fails, you'll still have to reconstitute
  53       things manually.
  54
  55     * You may want to consider using the Git sequencer, for
  56       which you can find a patch on the interwebs (I've never
  57       tried it before)
  58
  59 - The obvious scripts specific change that a new repository
  60   will have are the patches, but you should also check the
  61   autoinstall scripts if they do anything special.  In particular:
  62
  63     - If it's a PHP application, it's probably inserting a php.ini
  64       file and creating symlinks to it.  Be sure to replace the
  65       appropriate values with placeholders WIZARD_SESSIONNAME
  66       and WIZARD_TMPDIR
  67
  68     - You will probably need to generate relevant configuration
  69       files for each version using 'wizard prepare-config'
  70
  71
  72 Design decisions
  73 ----------------
  74
  75 - A mass tool will plow ahead even if the subcommand throws
  76   Wizard errors.  Normal errors will cause us to halt
  77   completely.  If the error that occured is within the realm
  78   of possibly, and should be dealt with by manual intervention
  79   (or even possibly a code change), and would not cause harm
  80   if we continued going, we will keep going, and let the maintainer
  81   deal later on with the errors en masse.
  82
  83 - We use the Google Python style guide.  See:
  84     http://code.google.com/p/soc/wiki/PythonStyleGuide
  85   However, we use 4-space indents, not 2-space indents.