Change repository name.

[wizard.git] / README

diff --git a/README b/README
index fe3e9aa41d1c2681a30b47377c8310699f706af1..717e89b2ebb8f93a99b612694f8737f4339b36a9 100644 (file)
--- a/README
+++ b/README
@@ -1,9 +1,63 @@
+Wizard is the new autoinstaller management system for
+scripts.mit.edu.  It resides in:
+
+    /mit/scripts/wizard
+
+It runs out of the box with the binaries in bin/; try
+`bin/wizard help` for some ideas on what to do.
+Repositories for autoinstall applications should reside
+in srv/, but are not versioned here.
+
+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.
+
+== 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