upgrade

vendor/doctrine/migrations/docs/en/reference/version_numbers.rst

@@ -0,0 +1,76 @@
+Version Numbers
+===============
+
+When :doc:`Generating Migrations <generating_migrations>` the newly created
+classes are generated with the name ``Version{date}`` with ``{date}`` having a
+``YmdHis`` `format <http://php.net/manual/en/function.date.php>`_. This format
+is important as it allows the migrations to be correctly ordered.
+
+Starting with version 1.5 when loading migration classes, Doctrine Migrations
+does a ``sort($versions, SORT_STRING)`` on version numbers. This can cause
+problems with custom version numbers:
+
+.. code-block:: php
+
+    <?php
+    $versions = [
+        'Version1',
+        'Version2',
+        // ...
+        'Version10',
+    ];
+    sort($versions, SORT_STRING);
+
+    var_dump($versions);
+    /*
+    array(3) {
+      [0] =>
+      string(8) "Version1"
+      [1] =>
+      string(9) "Version10"
+      [2] =>
+      string(8) "Version2"
+    }
+    */
+
+The custom version numbers above end up out of order which may cause damage
+to a database.
+
+It's **strongly recommended** that the ``Version{date}`` migration class name
+format is kept to and that the various :doc:`tools for generating migrations <generating_migrations>`
+be used.
+
+Should some custom migration numbers be necessary, keeping the version number
+the same length as the date format (14 total characters) and padding it to the
+left with zeros should work.
+
+.. code-block:: php
+
+    <?php
+
+    $versions = [
+        'Version00000000000001',
+        'Version00000000000002',
+        // ...
+        'Version00000000000010',
+        'Version20180107070000', // generated version
+    ];
+    sort($versions, SORT_STRING);
+
+    var_dump($versions);
+    /*
+    array(4) {
+      [0] =>
+      string(21) "Version00000000000001"
+      [1] =>
+      string(21) "Version00000000000002"
+      [2] =>
+      string(21) "Version00000000000010"
+      [3] =>
+      string(21) "Version20180107070000"
+    }
+    */
+
+Please note that migrating to this new, zero-padded format may require
+:ref:`manual version table intervention <managing-versions-table>` if the
+versions have previously been applied.