initial copy of text from email

diff --git a/lib/DBIx/Class/DeploymentHandler/Cookbook/CustomVersionHandler.pod b/lib/DBIx/Class/DeploymentHandler/Cookbook/CustomVersionHandler.pod
new file mode 100644 (file)
index 0000000..c4b6ee4
--- /dev/null
+++ b/lib/DBIx/Class/DeploymentHandler/Cookbook/CustomVersionHandler.pod
@@ -0,0 +1,69 @@
+DBIx::Class::DeploymentHandler (short name of DBICDH) is a tool for creating
+and upgrading your database.  In code it is a significant extension of
+DBIx::Class::Schema::Versioned; in spirit it is similar to ActiveRecord
+migrations, but at a different angle; with this tool you define your database's
+schema (and thus your migrations as well) with the perl classes instead of
+having your migrations define the database and *that* defining your schema.
+
+In general the tool is as simple as instantiating a DBICDH with a DBIC schema
+and calling ->install or ->upgrade.  But what makes DBICDH so much nicer
+than DBIx::Class::Schema::Versioned is it's extensibility.  DBICDH uses a
+combination of delegation and roles to allow for easy extension and code reuse.
+
+There are 3 basic parts (which are delegated to) in a typical DBICDH:
+
+   1. VersionHandler: The component that says what version to go to next
+   2. VersionStorage: The component that knows the version of the current
+   database 3. DeployMethod: The component that generates  and runs the sql
+   for migrations
+
+Again, typically people will go with the defaults, but if someone wants to
+do something unusual the first thing that will get overridden will probably
+be the VersionHandler.
+
+The default VersionHandler merely upgrades (and downgrades) with monotonic
+integers, increasing and decreasing respectively.  So if your database is at
+version 5 and you ask to upgrade to version 10, it will request the following
+discrete migrations to be deployed, in order: (5,6), (6,7), (7,8), (8,9),
+(9,10).
+
+Now lets say we are working on a large project and the database deploys
+are piling up.  Programmer Jack has set up a user authentication system.
+Programmer Steve has set up a verification system based on Jacks auth.
+Programmer Antonio has created a "friend" system in the spirit of social
+networking which is also based on Jacks auth.  Lastly Programmer Bethany
+has created a parts management system which does not depend on any of the
+other systems.
+
+Basically we can look at these as 4 distinct "versions" of the database, let's
+call them "Auth", "Verification", "Friends", and "Parts."  If code is managed
+carefully supposedly git can be used to see what code depends on other code.
+Let's pretend that we already have that part working.  Using such a tool
+would allow us to query git to discover what database versions depend on
+other versions and thus allow a non-linear migration path, allowing QC to
+take more time on more complex features without holding up the deployment
+of different parts of the live database.
+
+Lets do a quick example using the versions we've defined above.  QC requests
+to install "Verification" since it's a major feature that must exist in the
+live site even before a private beta.  Our overridden VersionHandler will
+query git and see that "Verification" depends on "Auth."  It will then query
+git again to see what "Auth" depends on and it will discover that "Auth"
+does not depend on anything else.  So it will run two migrations, first
+"Auth," and then "Verification."
+
+QC signs off on "Verification" and it gets deployed to the live site and
+the beta begins.  Meanwhile Antonio and Bethany both finish their respective
+subsystems.  QC requests that "Parts" be installed.  Because Parts depends on
+nothing else, it installs, QC likes it, it also gets deployed to the live beta.
+
+QC asks for Antonio's "Friend" system to be deployed, and because it only
+depends on "Auth," which is already installed, it has no new dependencies
+and is installed just fine.  Finally, QC signs off on this last subsystem
+and it is also deployed to the live site.
+
+The beauty of a system like the above described is that it allows the database
+to be upgraded based on what's ready as opposed to what people are working on.
+And because VersionHandler can easily be replaced with a more sophisticated
+VersionHandler the above is completely feasible, assuming the communication
+with git can be done (and it can.)