X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FDeploymentHandler%2FHandlesVersioning.pm;h=43f7ffb98a0354dea016a05995846114fa395242;hb=ed1721b92e5774426f63bbf69bc4b2c997fbf62e;hp=43f10093f4465ecf70879c3809db603d93567a26;hpb=5228a963e60b0c085a6ce930f9ba9dc66215676c;p=dbsrgits%2FDBIx-Class-DeploymentHandler.git

diff --git a/lib/DBIx/Class/DeploymentHandler/HandlesVersioning.pm b/lib/DBIx/Class/DeploymentHandler/HandlesVersioning.pm
index 43f1009..43f7ffb 100644
--- a/lib/DBIx/Class/DeploymentHandler/HandlesVersioning.pm
+++ b/lib/DBIx/Class/DeploymentHandler/HandlesVersioning.pm
@@ -9,6 +9,78 @@ requires 'previous_version_set';
 
 __END__
 
+=head1 DESCRIPTION
+
+Typically a VersionHandler will take a to_version and yeild an iterator of
+"version sets."
+
+A "version set" is basically an arrayref of "version numbers" (which we
+already know is vague as is.)  Typically a call to a VersionHandler's
+L</next_version_set> with a db version of 1 and a "to_version" of 5 will
+iterate over something like the following:
+
+ [1, 2]
+ [2, 3]
+ [3, 4]
+ [4, 5]
+ undef
+
+or maybe just
+
+ [1, 5]
+ undef
+
+Really how the version set's are arranged is up to the VersionHandler being
+used.
+
+In some cases users will not want versions to have inherent "previous
+versions," which is why the version set is an C<ArrayRef>.  In those cases the
+user should opt to returning merely the version that the database is being
+upgraded to in each step.
+
+One idea that has been suggested to me has been to have a form of dependency
+management of the database "versions."  In this case the versions are actually
+more like features that may or may not be applied.  For example, one might
+start with version 1 and have a feature (version) C<users>.
+
+Each feature might require that the database be upgraded to another version
+first.  If one were to implement a system like this, here is how the
+VersionHandler's L</next_version_set> might look.
+
+ to_version = "users", db_version = 1
+ [3]
+ [5]
+ ["users"]
+ undef
+
+So what just happened there is that C<users> depends on version 5, which depends
+on version 3, which depends on version 1, which is already installed.  To be
+clear, the reason we use single versions instead of version pairs is because
+there is no inherent order for this type of database upgraded.
+
+=head2 Downgrades
+
+For the typical case I'd like downgrades to be easy for users to perform and
+understand.  That means that with the first two examples give above we can use
+the L</previous_version_set> iterator to yeild the following:
+
+
+ db_version = 5, to_version=1
+ [4, 5]
+ [3, 4]
+ [2, 3]
+ [1, 2]
+ undef
+
+or maybe just
+
+ [1, 5]
+ undef
+
+Note that we do not swap the version number order.  This allows us to remain
+consistent in our version set abstraction, since a version set really just
+describes a version change, and not necesarily a defined progression.
+
 =method next_version_set
 
  print 'versions to install: ';
@@ -31,37 +103,24 @@ installed to upgrade to C<< $dh->to_version >>.
 return an arrayref describing each version that needs to be
 "installed" to downgrade to C<< $dh->to_version >>.
 
-# normally a VersionHandler will take
-# a to_version and yeild an iterator of
-# "version sets" or something like that.
-#
-# A "version set" is basically an arrayref
-# of "version numbers" (which we already know
-# is vague as is.)  Typically an call to a
-# VH w/ a db version of 1 and a "to_version"
-# of 5 will iterate over something like this:
-# [1, 2]
-# [2, 3]
-# [3, 4]
-# [4, 5]
-#
-# Of course rob wants to be able to have dep
-# management with his versions, so I *think* his
-# would work like this:
-#
-# to_version = 7, db_version = 1
-# [1]
-# [5]
-# [7]
-#
-# Because 7 depended on 5, 5 was installed first;
-# note that this potentially never released module
-# doesn't use version pairs, instead it just yeilds
-# versions.  Version pairs are too much work for users
-# to have to deal with in that sitation.  We may
-# actually switch to this for other versioners.
-#
-# The upshot of all this is that the DeploymentMethod
-# needs to be able to take an ArrayRef[VersionNumber],
-# instead of just a pair of VersionNumber.
+=head1 KNOWN IMPLEMENTATIONS
+
+=over
+
+=item *
+
+L<DBIx::Class::DeploymentHandler::VersionHandler::Monotonic>
+
+=item *
+
+L<DBIx::Class::DeploymentHandler::VersionHandler::DatabaseToSchemaVersions>
+
+=item *
+
+L<DBIx::Class::DeploymentHandler::VersionHandler::ExplicitVersions>
+
+=back
+
+__END__
+
 vim: ts=2 sw=2 expandtab