More docs and a few minor changes to the Timeline.

gsomoza · Jul 13, 2015 · 0aefe0c · 0aefe0c
1 parent 2126947
commit 0aefe0c
Show file tree

Hide file tree

Showing 9 changed files with 349 additions and 99 deletions.
diff --git a/docs/en/examples/migrations.txt b/docs/en/examples/migrations.txt
diff --git a/docs/en/getting-started.txt b/docs/en/getting-started.txt
@@ -2,7 +2,7 @@ Getting Started
 ===============
 
 Before you get started its important you understand what this particular library is about. Make sure you read the
-introduction in the :doc:`index` and the following architecture overview.
+:doc:`introduction <index>` and the following architecture overview.
 
 Overview
 --------
@@ -11,14 +11,15 @@ The Baleen projects aims to make migrations easier for anyone. All projects unde
 be related to migrations in one way or another.
 
 Baleen Migrations is the core of the Baleen project. It provides a domain model on top of which other migration
-libraries can run their migrations.
+libraries can run their :term:`migration scripts <migration>`.
 
 In other words: Baleen Migrations alone is NOT supposed to be an end-user solution. Its meant to be used by other
 repositories such as Doctrine Migrations, and it is those repositories that would become the end-user libraries that
 framework users consume.
 
 So if you came to this repository to find a new migrations solution then you're not quite in the right place yet.
-Instead, please refer to :doc:`implementations` libraries - we hope there you'll find what you're looking for.
+Instead, please refer to the :doc:`implementations <implementations>` list of libraries - we hope there you'll find what
+you're looking for.
 
 Installation
 ------------

diff --git a/docs/en/glossary.txt b/docs/en/glossary.txt
@@ -0,0 +1,74 @@
+Glossary
+========
+
+Baleen Migrations has been carefully engineered with the goal of satisfying as many types migration as possible.
+Whether its a database migration, image transformations or even source code, this module aims to help in the process of
+pragmatically transform virtually anything from one state to the other, taking it through a series of pre-defined
+steps (migrations).
+
+The purpose of this document is to standardise the use of certain terms throughout the context of this project, as well
+as to provide information about the different models that make up the "migrations" domain.
+
+.. glossary::
+
+   Ecosystem
+         Refers to a group of objects related to each other that work towards a single purpose: migrating a
+         :term:`Target Resource` from point A to point B. In this project, some of those objects are (in no particular
+         order):
+
+             * :term:`Timeline`
+             * :term:`Repository`
+             * :term:`Storage`
+             * :term:`Version`
+             * :term:`Migration`
+
+         A single application can have any number of Migration Ecosystems, but its most common to find only one or two per
+         project.
+
+   Migration
+      (noun) A migration is a class that can execute an incremental (when migrating / "going up") or decremental (when
+      reverting / "going down") transformation on a target resource. All classes that implement ``MigrationInterface``
+      are considered a migration.
+
+   Migrate
+      (verb) Verb used to refer to the process of running one or more migrations.
+
+   Migrated
+      (adj.) If something is "migrated" then it means that the migration's ``up()`` method has executed successfully
+      and the corresponding version is (or will immediately be) stored in the :term:`Storage`. The opposite is true
+      if something has NOT been migrated.
+
+   Target Resource
+      During a migrationm the target resource or migration target is WHAT's being migrated. It can be a database, an
+      image, other files, etc. There should only be one target resource for any given Migration Ecosystem.
+
+   Repository
+      The Repository is an object that knows where to find term:`migrations <migration>`.
+
+   Storage
+      The Storage object is used to persist information about which :term:`Versions <version>` have already been
+      migrated.
+
+   Timeline
+      The Timeline is an object that is in charge of executing migrations in bulk using certain pre-defined algorithms.
+      It holds an immutable :term:`Version Collection`.
+
+   Version
+      A Version is a lightweight entity that is persisted into the :term:`Storage` and holds state information about
+      a :term:`Migration`. Currently the only state information being saved is whether the Version is :term:`migrated`
+      or not. If a Version is present in the :term:`Storage` then it means that Version has already been migrated.
+
+   Version Collection
+      A special object to represent and sort a set of Collection. Its important to note that it behaves as an ordered
+      set of elements.
+
+Core Models
+-----------
+
+.. toctree::
+   :maxdepth: 2
+
+   core-concepts/migration
+   core-concepts/timeline
+
+
diff --git a/docs/en/index.txt b/docs/en/index.txt
@@ -11,21 +11,21 @@ implementation:
 * WHAT is going to be migrated? It could be a database, images, documents, etc.
 * HOW its going to be migrated? You can wrap each migration into DB transactions. Or not, its up to you.
 * What to do when a migration fails? We'll let you know WHEN it happens, but its up to you to decide what to do
-  (e.g. cancel the transaction).
+  (e.g. cancel the transaction / re-throw the exception, etc).
 
 Contents:
 
 .. toctree::
-   :glob:
+   :numbered:
    :maxdepth: 2
 
    getting-started
+   migration
+   timeline
    implementations
-   examples
-   examples/*
+   glossary
 
-Indices and tables
+Indices and Tables
 ==================
 
 * :ref:`genindex`
-
diff --git a/docs/en/migration.txt b/docs/en/migration.txt
@@ -0,0 +1,169 @@
+Migration
+=========
+
+.. glossary::
+
+
+
+A migration in Baleen is a class that implements ``MigrationInterface``. It can optionally implement one or more
+additional interfaces to describe special *capabilities*.
+
+MigrationInterface
+------------------
+
+All :term:`migration` classes must implement ``MigrationInterface``, which declares the ``up()`` and ``down()`` methods.
+Each of those methods should modify the :term:`target resource` symmetrically:
+
+    * UP: Describes what happens when the resource moves up (or forwards) in the Timeline.
+    * DOWN: Describes how to revert / rollback the resource if ``up`` has already been executed.
+
+The following snippet illustrates a simple migration that creates (or destroys) a table. Note how the up and down
+methods are perfectly symmetrical to each other:
+
+.. code-block:: php
+
+    <?php
+    class v001_AddHireDateToStaff extends MigrationInterface
+    {
+
+        // a constructor would go here to set up the connection
+
+        /**
+          * Adds a "hire_date" column to the staff table.
+          */
+        public function up() {
+            $this->connection->exec("ALTER TABLE staff ADD hire_date date");
+        }
+
+        /**
+          * Removes the "hire_date" column from the staff table.
+          */
+        public function down() {
+            $this->connection->exec("ALTER TABLE staff REMOVE hire_date date");
+        }
+    }
+
+Additional Capabilities
+------------------------
+
+Additional interfaces can be used to indicate special features available for a certain migration. Baleen supplies a few
+common interfaces for commonly-used features, but more can be created to suit specific needs.
+
+OptionsAwareInterface
+######################
+
+A migration that implements this interface must receive an ``Options`` object after being
+instantiated. The ``Options`` object will include contextual information that could be useful for the migration. Refer
+to the ``Options`` class documentation for more information.
+
+TransactionAwareInterface
+#########################
+
+A migration that implements this interface must implement a set of methods that will aid in generating transactions.
+Useful for example to wrap ``up()`` or ``down()`` commands into database transactions. The methods declared in this
+interface are:
+
+    * ``begin()``: called right before executing the migration (i.e. the ``up()`` or ``down()`` method).
+    * ``finish()``: called right after the migration finished executing without any exceptions.
+    * ``abort(Exception)``: called if any exception is fired during the execution of the migration. The exception is
+      passed as the only parameter. The ``abort`` method must recover the resource from the exception (e.g. roll-back
+      the transaction) and optionally re-throw the exception if needed.
+
+Other Capabilities
+##################
+
+Additional interfaces can be specified to deal with special features required by any particular migration process. In
+order to make this easy to customise, migrations are run through a configurable *Command Bus* pattern.
+
+Example Migrations
+------------------
+
+For the purposes of this example, imagine the following classes are each located on a separate file under a folder in
+your project called ``./migrations``.
+
+The first file declares a sample abstract class to incorporate common functionality. It is of course up to the user
+whether something like this is really required or not.
+
+File ``./migrations/AbstractPDOMigration.php`` :
+
+.. code-block:: php
+
+    <?php
+    use Baleen\Migration\MigrationInterface;
+    use Baleen\Migration\Capabilities;
+    use Baleen\Migration\MigrationInterface;
+    use Baleen\Migration\RunOptions;
+
+    /**
+     * You can be as creative as you want here. The only requirement is to implement
+     * MigrationInterface.
+     */
+    class AbstractPDOMigration
+        implements MigrationInterface,
+                   Capabilities/OptionsAwareInterface,
+                   Capabilities/TransactionAwareInterface
+    {
+        /** @var PDO **/
+        protected $connection; // gets initialised on the constructor
+
+        /** @var RunOptions **/
+        protected $options;
+
+        public function __construct (PDO $connection) {
+            $this->connection = $connection;
+        }
+
+        public function begin() {
+            $this->connection->beginTransaction();
+        }
+
+        public function finish() {
+            $this->connection->commit();
+        }
+
+        public function abort() {
+            $this->connection->rollBack();
+        }
+
+        public function setOptions(RunOptions $options) {
+            $this->options = $options;
+        }
+    }
+
+And now the concrete migrations:
+
+File ``./migrations/v001_AddHireDateToStaff.php`` :
+
+.. code-block:: php
+
+    <?php
+    class v001_AddHireDateToStaff extends AbstractPDOMigration
+    {
+        public function up() {
+            $this->connection->exec("ALTER TABLE staff ADD hire_date date");
+        }
+
+        public function down() {
+            $this->connection->exec("ALTER TABLE staff ADD hire_date date");
+        }
+    }
+
+File ``./migrations/v002_SeedJoeBloggs.php`` :
+
+.. code-block:: php
+
+    <?php
+    class v002_SeedJoeBloggs extends AbstractPDOMigration
+    {
+        public function up() {
+            $this->connection->exec(
+                "INSERT INTO staff (id, first, last) VALUES (23, 'Joe', 'Bloggs')"
+            );
+        }
+
+        public function down() {
+            $this->connection->exec("DELETE FROM staff WHERE id = 23");
+        }
+    }
+
+    // ... etc - for the purposes of this example imagine there are 100 migrations