Update README and TODO.

[wizard.git] / README

diff --git a/README b/README
index 9537da723f24faf772f9b6ecd3667138911e9170..7382dfa9ab0ec3938875eb917c377c8be24b4440 100644 (file)
--- a/README
+++ b/README
@@ -1,14 +1,72 @@
+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()
 
-Design decision:
+- 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
@@ -16,3 +74,6 @@ Design decision:
   (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