Merge pull request #42 from samwilson/guide

An update to the guide

config/userguide.php

@@ -0,0 +1,23 @@
+<?php defined('SYSPATH') OR die('No direct script access.');
+
+return array(
+	// Leave this alone
+	'modules' => array(
+
+		// This should be the path to this modules userguide pages, without the 'guide/'. Ex: '/guide/modulename/' would be 'modulename'
+		'minion-migrations' => array(
+
+			// Whether this modules userguide pages should be shown
+			'enabled' => TRUE,
+			
+			// The name that should show up on the userguide index page
+			'name' => 'Minion Migrations',
+
+			// A short description of this module, shown on the index page
+			'description' => "Migration tasks for Kohana's Minion CLI framework.",
+			
+			// Copyright message, shown in the footer for this module
+			'copyright' => '&copy; 2008–2012 Kohana Team',
+		)	
+	)
+);

guide/minion-migrations/generating.md

@@ -0,0 +1,24 @@
+# New Migrations
+
+Every set of modifications to the database schema should be done through a new Migration.
+
+The task for this is `migrations:new`, and its full documentation is available with the usual help command:
+
+	php index.php migrations:new --help
+
+The `migrations:new` task takes three parameters: *group*, *location*, and *description*.
+A new file will be created, containing the skeleton of a child class of [Minion_Migration_Base]
+that must be fleshed out with code to perform the migration (and its reversal).
+
+## Group
+
+Groups provide a means to run particular sets of Migrations separately.
+Every Migration must be in a group.
+
+For modules' Migrations, the group name is usually the same as the module name (or at least prefixed with it).
+
+## Description
+
+The description is optional, and if provided will be turned into a normalised suffix
+for the Migration class's file (e.g. `20130529140938_initial-installation.php`)
+and also shown in the output of the `status` and `run` tasks.

guide/minion-migrations/index.md

@@ -0,0 +1,33 @@
+# Minion Migrations
+
+*Migrations? But I'm not leaving the country!*
+
+The term "migration" is used to describe the movement from one location to another.
+In the context of databases it refers to managing differences between schemas.
+In essence, it's version control for databases, and this module makes it easy to roll back to earlier versions at any time.
+
+Every set of changes to the database schema is carried out from a Migration,
+which is just a class that extends [Minion_Migration_Base].
+These Migration classes each contain an `up()` and `down()` method,
+which do the work of applying changes to the database schema and undoing these changes, respectively.
+
+Once a Migration has been released (i.e. has possibly been run on a production system) it should not be modified.
+Instead, new Migrations must be created.
+
+## Metadata table
+
+The first time a Migration is run, a special table (by default called `minion_migrations`) is created
+in which to store information about which Migrations have been applied.
+
+The table name can be customised with the `minion/migration.table` [configuration value](../kohana/files/config).
+
+The table definition is as follows:
+
+	CREATE TABLE `<table_name>` (
+		`timestamp` varchar(14) NOT NULL,
+		`description` varchar(100) NOT NULL,
+		`group` varchar(100) NOT NULL,
+		`applied` tinyint(1) DEFAULT '0',
+		PRIMARY KEY (`timestamp`,`group`),
+		UNIQUE KEY `MIGRATION_ID` (`timestamp`,`description`)
+	) ENGINE=MyISAM DEFAULT CHARSET=utf8;

guide/minion-migrations/menu.md

@@ -0,0 +1,3 @@
+## [Minion Migrations]()
+- [Generating](generating)
+- [Running](running)

guide/minion-migrations/running.md

@@ -0,0 +1,50 @@
+# Running Migrations
+
+The reference documentation for running migrations can be viewed in the usual way:
+
+	php index.php migrations:run --help
+
+## Find out where you are
+
+At any time, the current status of completed and pending migrations can be found with:
+
+	php index.php migrations:status
+
+There are no options for `status` (other than `--help`).
+
+## Go up
+
+To migrate your schema to the latest possible version run the command:
+
+	php index.php migrations:run --up
+
+This will run all migrations that haven't yet been applied.
+
+## Go down
+
+To reverse all migrations (i.e. to delete all the tables in your schema) run this command:
+
+	php index.php migrations:run --down
+
+Note that this will actually only go down as far as the *lowest migration*
+[configuration value](../kohana/files/config) (defined by `minion/migration.lowest_migration`).
+
+## Go over there
+
+If you want to a specific version of your schema then you can use the `--to` switch,
+which accepts either a migration's timestamp or a relative pointer to a migration.
+This must be used with the `--group` switch.
+
+	# Migrate the schema 5 versions down
+	--to=-5
+	
+	# Migrate the schema 10 versions up:
+	--to=+10
+	
+	# Migrate to a specific version
+	--to=201102190811
+
+## Look before you leap
+
+If you want to see what a Migration is going to do then you can use the `--dry-run` switch
+and the SQL will be printed to the console instead of being executed.