X-Git-Url: https://scripts.mit.edu/gitweb/wizard.git/blobdiff_plain/9baefc885a1156d64ddc3389a77382aec4a3173a..a29acb618699431bf1fdd2c7df6d3b0a9e0282e0:/README

diff --git a/README b/README
index 7eb7289..dc4b28a 100644
--- a/README
+++ b/README
@@ -1,16 +1,77 @@
+Wizard is the new autoinstaller management system for
+scripts.mit.edu.  This is a developer oriented introduction,
+and will get placed in doc/ soon.
+
+
+Compatibility
+-------------
+
 This is Python 2.6 only!
 
+
+The 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
-    Add the line "import commandname"
-- lib/wizard/command/commandname.py
-    Implement your command there as commandname()
 
-Design decision:
+- wizard/command/command_name.py
+    Implement your command there as main(). Copy the function
+    signature and scaffolding from another file; it's non-trivial
+    Underscores in the module-name are referenced using dashes.
+
+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 to create self-documenting
+code.  Don't make helper functions for one-liners.  Place
+all error classes at the bottom.
+
+
+Notes for repository creation
+-----------------------------
+
+See TODO for full instructions.
+
+- You are not going to be able to doctor a perfect repository
+  from scratch.
+
+    * If you have a simple change to a commit message, or
+      something that you don't really need interactive control
+      over (such as methodically rm'ing a file), git
+      filter-branch is very superior.
+
+    * 'git rebase -p -i' can be used to rewrite history interactively.
+      Doing this will nuke any manual merge resolution you
+      may have done (which may be a lot), thus, I highly
+      recommend that you enable rerere (rerere.enabled = true)
+      so that Git can automatically merge things for you.
+      If the merge fails, you'll still have to reconstitute
+      things manually.
+
+    * You may want to consider using the Git sequencer, for
+      which you can find a patch on the interwebs (I've never
+      tried it before)
+
+- 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 using 'wizard prepare-config'
+
+
+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
@@ -18,3 +79,11 @@ 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.
+
+  If the error is due to an error in our toolchain (and thus
+  many installs can be fixed by fixing our end), we want to
+  be able to re-run the mass tool with minimal fuss.
+
+- We use the Google Python style guide.  See:
+    http://code.google.com/p/soc/wiki/PythonStyleGuide
+  However, we use 4-space indents, not 2-space indents.