X-Git-Url: https://scripts.mit.edu/gitweb/wizard.git/blobdiff_plain/193c996c0df943f6bd955bdb475548b04ec9e711..2e5b70b9d9a09d3cdb7d1efa1c2b20650125e48f:/README

diff --git a/README b/README
index fe3e9aa..7382dfa 100644
--- a/README
+++ b/README
@@ -1,9 +1,79 @@
+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 commandname()
+
+- 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