README

   1 Wizard Autoinstall
   2 ==================
   3
   4 Wizard is a next-generation autoinstall management system with
   5 an eye towards flexibility and scalability.  It is licensed
   6 under the MIT license (you can view the license contents in
   7 LICENSE).
   8
   9
  10 Compatibility
  11 -------------
  12
  13 This is Python 2.6 only!
  14
  15
  16 The command package
  17 -------------------
  18
  19 To add a new command to wizard, you need to touch the following
  20 locations:
  21
  22 - bin/wizard
  23     Add a line describing your command in the helpstring
  24
  25 - wizard/command/command_name.py
  26     Implement your command there as main(). Copy the function
  27     signature and scaffolding from another file; it's non-trivial
  28     Underscores in the module-name are referenced using dashes.
  29
  30 As a command file, you're expected to have a main() and parse_args()
  31 function.  Try to keep main() one to two page function that can
  32 be browsed for a descriptive overview of what the command does
  33 internally.  Use helper functions to create self-documenting
  34 code.  Don't make helper functions for one-liners.  Place
  35 all error classes at the bottom.
  36
  37
  38 Notes for repository creation
  39 -----------------------------
  40
  41 See documentation for full instructions.
  42
  43 - You are not going to be able to doctor a perfect repository
  44   from scratch.
  45
  46     * If you have a simple change to a commit message, or
  47       something that you don't really need interactive control
  48       over (such as methodically rm'ing a file), git
  49       filter-branch is very superior.
  50
  51     * 'git rebase -p -i' can be used to rewrite history interactively.
  52       Doing this will nuke any manual merge resolution you
  53       may have done (which may be a lot), thus, I highly
  54       recommend that you enable rerere (rerere.enabled = true)
  55       so that Git can automatically merge things for you.
  56       If the merge fails, you'll still have to reconstitute
  57       things manually.
  58
  59     * You may want to consider using the Git sequencer, for
  60       which you can find a patch on the interwebs (I've never
  61       tried it before)
  62
  63 - The obvious scripts specific change that a new repository
  64   will have are the patches, but you should also check the
  65   autoinstall scripts if they do anything special.  In particular:
  66
  67     - If it's a PHP application, it's probably inserting a php.ini
  68       file and creating symlinks to it.  Be sure to replace the
  69       appropriate values with placeholders WIZARD_SESSIONNAME
  70       and WIZARD_TMPDIR (Scripts)
  71
  72     - You will probably need to generate relevant configuration
  73       files for each version using 'wizard prepare-config'
  74
  75
  76 Design decisions
  77 ----------------
  78
  79 - A mass tool will plow ahead even if the subcommand throws
  80   Wizard errors.  Normal errors will cause us to halt
  81   completely.  If the error that occured is within the realm
  82   of possibly, and should be dealt with by manual intervention
  83   (or even possibly a code change), and would not cause harm
  84   if we continued going, we will keep going, and let the maintainer
  85   deal later on with the errors en masse.
  86
  87   If the error is due to an error in our toolchain (and thus
  88   many installs can be fixed by fixing our end), we want to
  89   be able to re-run the mass tool with minimal fuss.
  90
  91 - We use the Google Python style guide.  See:
  92     http://code.google.com/p/soc/wiki/PythonStyleGuide
  93   However, we use 4-space indents, not 2-space indents.