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

diff --git a/README b/README
index 7382dfa..5d0b88d 100644
--- a/README
+++ b/README
@@ -1,29 +1,20 @@
-Wizard is the new autoinstaller management system for
-scripts.mit.edu.  It resides on not-backward.mit.edu at:
+Wizard Autoinstall
+==================
 
-    /wizard
+Wizard is a next-generation autoinstall management system with
+an eye towards flexibility and scalability.  It is licensed
+under the MIT license (you can view the license contents in
+LICENSE).
 
-Developers, read on:
 
-== Compatibility ==
+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 ==
+The command package
+-------------------
 
 To add a new command to wizard, you need to touch the following
 locations:
@@ -31,27 +22,43 @@ locations:
 - bin/wizard
     Add a line describing your command in the helpstring
 
-- wizard/command/__init__.py
-    Add the line "import commandname"
-
-- wizard/command/commandname.py
+- 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 liberally.  Place all error classes
-at the bottom.
+internally.  Use helper functions to create self-documenting
+code.  Don't make helper functions for one-liners.  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 for repository creation
+-----------------------------
 
-== Notes when fiddling with application repositories ==
+See documentation for full instructions.
 
-- 'git rebase -p -i' is your friend.  Use it to rewrite history!
+- 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
@@ -60,12 +67,14 @@ needs to be written for each autoinstaller.  These go here.
     - 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
+      and WIZARD_TMPDIR (Scripts)
 
     - You will probably need to generate relevant configuration
-      files for each version
+      files for each version using 'wizard prepare-config'
 
-== Design decisions ==
+
+Design decisions
+----------------
 
 - A mass tool will plow ahead even if the subcommand throws
   Wizard errors.  Normal errors will cause us to halt
@@ -75,5 +84,10 @@ needs to be written for each autoinstaller.  These go here.
   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.