+Wizard is the new autoinstaller management system for
+scripts.mit.edu. It resides on not-backward.mit.edu at:
+
+ /wizard
+
+Developers, read on:
+
+== Compatibility ==
+
+This is Python 2.6 only!
+
+== Module overview ==
+
+- deploy: object model for autoinstall deployments, applications
+ and versions
+
+- shell: subprocess wrapper that does logging, error handling
+ and asynchronous processing
+
+- sset: "serialized set", use in a mass* command for tracking
+ what installs have already been seen and successfully processed
+
+- util: miscellaneous utility functions, right now mostly one-off
+ parsing and convenience wrappers
+
+== 'command' package ==
+
To add a new command to wizard, you need to touch the following
locations:
- bin/wizard
Add a line describing your command in the helpstring
-- lib/wizard/command/__init__.py
+
+- wizard/command/__init__.py
Add the line "import commandname"
-- lib/wizard/command/commandname.py
- Implement your command there as main()
+
+- wizard/command/commandname.py
+ Implement your command there as main(). Copy the function
+ signature and scaffolding from another file; it's non-trivial
+
+As a command file, you're expected to have a main() and parse_args()
+function. Try to keep main() one to two page function that can
+be browsed for a descriptive overview of what the command does
+internally. Use helper functions liberally. Place all error classes
+at the bottom.
+
+== 'app' package ==
+
+There is a certain amount of application specific code that
+needs to be written for each autoinstaller. These go here.
+
+== Notes when fiddling with application repositories ==
+
+- 'git rebase -p -i' is your friend. Use it to rewrite history!
+
+- The obvious scripts specific change that a new repository
+ will have are the patches, but you should also check the
+ autoinstall scripts if they do anything special. In particular:
+
+ - If it's a PHP application, it's probably inserting a php.ini
+ file and creating symlinks to it. Be sure to replace the
+ appropriate values with placeholders WIZARD_SESSIONNAME
+ and WIZARD_TMPDIR
+
+ - You will probably need to generate relevant configuration
+ files for each version
+
+== Design decisions ==
+
+- A mass tool will plow ahead even if the subcommand throws
+ Wizard errors. Normal errors will cause us to halt
+ completely. If the error that occured is within the realm
+ of possibly, and should be dealt with by manual intervention
+ (or even possibly a code change), and would not cause harm
+ if we continued going, we will keep going, and let the maintainer
+ deal later on with the errors en masse.
+
+- We use the Google Python style guide. See:
+ http://code.google.com/p/soc/wiki/PythonStyleGuide