+Wizard Autoinstall
+==================
+
+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).
+
+
+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()
+
+- 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 documentation 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 (Scripts)
+
+ - 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
+ 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.
+
+ 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.