Merge pull request denisenkom#264 from twrobel3/feature/migrations-re…

…adme

Fill out MIGRATIONS.md with migration format and best practice notes

MIGRATIONS.md

@@ -1,5 +1,81 @@
 # Migrations
 
-## Best practices: How to write migrations.
+## Migration Filename Format
 
-@TODO
+A single logical migration is represented as two separate migration files, one
+to migrate "up" to the specified version from the previous version, and a second
+to migrate back "down" to the previous version.  These migrations can be provided
+by any one of the supported [migration sources](./README.md#migration-sources).
+
+The ordering and direction of the migration files is determined by the filenames
+used for them.  `migrate` expects the filenames of migrations to have the format:
+
+    {version}_{title}.up.{extension}
+    {version}_{title}.down.{extension}
+
+The `title` of each migration is unused, and is only for readability.  Similarly,
+the `extension` of the migration files is not checked by the library, and should
+be an appropriate format for the database in use (`.sql` for SQL variants, for
+instance).
+
+Versions of migrations may be represented as any 64 bit unsigned integer.
+All migrations are applied upward in order of increasing version number, and
+downward by decreasing version number.
+
+Common versioning schemes include incrementing integers:
+
+    1_initialize_schema.down.sql
+    1_initialize_schema.up.sql
+    2_add_table.down.sql
+    2_add_table.up.sql
+    ...
+
+Or timestamps at an appropriate resolution:
+
+    1500360784_initialize_schema.down.sql
+    1500360784_initialize_schema.up.sql
+    1500445949_add_table.down.sql
+    1500445949_add_table.up.sql
+    ...
+
+But any scheme resulting in distinct, incrementing integers as versions is valid.
+
+It is suggested that the version number of corresponding `up` and `down` migration
+files be equivalent for clarity, but they are allowed to differ so long as the
+relative ordering of the migrations is preserved.
+
+The migration files are permitted to be empty, so in the event that a migration
+is a no-op or is irreversible, it is recommended to still include both migration
+files, and either leaving them empty or adding a comment as appropriate.
+
+## Migration Content Format
+
+The format of the migration files themselves varies between database systems.
+Different databases have different semantics around schema changes and when and
+how they are allowed to occur (for instance, if schema changes can occur within
+a transaction).
+
+As such, the `migrate` library has little to no checking around the format of
+migration sources.  The migration files are generally processed directly by the
+drivers as raw operations.
+
+## Reversibility of Migrations
+
+Best practice for writing schema migration is that all migrations should be
+reversible.  It should in theory be possible for run migrations down and back up
+through any and all versions with the state being fully cleaned and recreated
+by doing so.
+
+By adhering to this recommended practice, development and deployment of new code
+is cleaner and easier (cleaning database state for a new feature should be as
+easy as migrating down to a prior version, and back up to the latest).
+
+As opposed to some other migration libraries, `migrate` represents up and down
+migrations as separate files.  This prevents any non-standard file syntax from
+being introduced which may result in unintended behavior or errors, depending
+on what database is processing the file.
+
+While it is technically possible for an up or down migration to exist on its own
+without an equivalently versioned counterpart, it is strongly recommended to
+always include a down migration which cleans up the state of the corresponding
+up migration.