Set admin e-mail address properly on MediaWiki >= 1.18.0

[wizard.git] / README

diff --git a/README b/README
index 505e8f595e0a3c483886801efed43534d90c283e..5d0b88d39507c0d7aca33e20eaacc6d7e815eb14 100644 (file)
--- 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!
 
 
 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:
 
 To add a new command to wizard, you need to touch the following
 locations:


@@ -31,24 +22,43 @@ locations:
 - bin/wizard
     Add a line describing your command in the helpstring
 
 - bin/wizard
     Add a line describing your command in the helpstring
 

-- 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
     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
 
 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 ==
+Notes for repository creation
+-----------------------------

 
 

-There is a certain amount of application specific code that
-needs to be written for each autoinstaller.  These go here.
+See documentation for full instructions.

 
 

-== Notes when fiddling with application repositories ==
+- You are not going to be able to doctor a perfect repository
+  from scratch.

 
 

-- 'git rebase -p -i' is your friend.  Use it to rewrite history!
+    * 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
 
 - The obvious scripts specific change that a new repository
   will have are the patches, but you should also check the


@@ -57,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
     - 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
 
     - 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
 
 - A mass tool will plow ahead even if the subcommand throws
   Wizard errors.  Normal errors will cause us to halt


@@ -72,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 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
 - 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.