From 0fbb0b56a8415f5d682c8b4e00e89dc99d276c97 Mon Sep 17 00:00:00 2001
From: Mark Story <mark@mark-story.com>
Date: Wed, 3 Apr 2024 23:51:09 -0400
Subject: [PATCH] Add docs on the intended upgrade process.

I'll continue to expand this as necessary with new findings.
---
 docs/en/contents.rst                     |  1 +
 docs/en/upgrading-to-builtin-backend.rst | 57 ++++++++++++++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 docs/en/upgrading-to-builtin-backend.rst

diff --git a/docs/en/contents.rst b/docs/en/contents.rst
index 1459b1f1..899c35b1 100644
--- a/docs/en/contents.rst
+++ b/docs/en/contents.rst
@@ -3,3 +3,4 @@
     :caption: CakePHP Migrations
 
     /index
+    /upgrading-to-builtin-backend
diff --git a/docs/en/upgrading-to-builtin-backend.rst b/docs/en/upgrading-to-builtin-backend.rst
new file mode 100644
index 00000000..bc4d56f6
--- /dev/null
+++ b/docs/en/upgrading-to-builtin-backend.rst
@@ -0,0 +1,57 @@
+Upgrading to the builtin backend
+################################
+
+As of migrations XXX there is a new migrations backend that uses CakePHP's
+database abstractions and ORM. Longer term this will allow for phinx to be
+removed as a dependency. This greatly reduces the dependency footprint of
+migrations.
+
+What is the same?
+=================
+
+Your migrations shouldn't have to change much to adapt to the new backend.
+The migrations backend implements all of the phinx interfaces and can run
+migrations based on phinx classes. If your migrations don't work in a way that
+could be addressed by the changes outlined below, please open an issue, as we'd
+like to maintain as much compatibility as we can.
+
+What is different?
+==================
+
+If your migrations are using the ``AdapterInterface`` to fetch rows or update
+rows you will need to update your code. If you use ``Adapter::query()`` to
+execute queries, the return of this method is now
+``Cake\Database\StatementInterface`` instead. This impacts ``fetchAll()``,
+and ``fetch()``::
+
+    // This
+    $stmt = $this->getAdapter()->query('SELECT * FROM articles');
+    $rows = $stmt->fetchAll();
+
+    // Now needs to be
+    $stmt = $this->getAdapter()->query('SELECT * FROM articles');
+    $rows = $stmt->fetchAll('assoc');
+
+Similar changes are for fetching a single row::
+
+    // This
+    $stmt = $this->getAdapter()->query('SELECT * FROM articles');
+    $rows = $stmt->fetch();
+
+    // Now needs to be
+    $stmt = $this->getAdapter()->query('SELECT * FROM articles');
+    $rows = $stmt->fetch('assoc');
+
+Enabling the new backend
+========================
+
+The new backend can be enabled through application configuration. Add the
+following to your ``config/app.php``::
+
+    return [
+        // Other configuration.
+        'Migrations' => ['backend' => 'builtin'],
+    ];
+
+If your migrations have problems running with the builtin backend, removing this
+configuration option will revert to using phinx.