From 6b7d880330911ceb4a94b2bc8399f2752c59acab Mon Sep 17 00:00:00 2001
From: Dimitri Yatsenko <dimitri.yatsenko@gmail.com>
Date: Mon, 17 Aug 2026 10:23:02 -0500
Subject: [PATCH] =?UTF-8?q?docs(migration):=20state=20the=20target=20versi?=
 =?UTF-8?q?ons=20=E2=80=94=20migrate=200.x=20straight=20to=20latest=202.x?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The migration guide framed the target only as '2.0'. Clarify that a legacy (0.x)
pipeline migrates directly to the latest 2.x release (currently 2.3) in a single
upgrade — no stepping through 2.0 -> 2.1 -> 2.2 -> 2.3. '2.0' in the guide is the
migration surface (type system, codecs, unified stores); 2.1-2.3 build on it with
no extra migration steps. Retitle to 'Migrate to DataJoint 2.x' (H1 + nav).
---
 mkdocs.yaml                  |  2 +-
 src/how-to/migrate-to-v20.md | 21 +++++++++++++++++++--
 2 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/mkdocs.yaml b/mkdocs.yaml
index 29b5c7d8..31bb95e2 100644
--- a/mkdocs.yaml
+++ b/mkdocs.yaml
@@ -99,7 +99,7 @@ nav:
           - Manage Large Data: how-to/manage-large-data.md
           - Clean Up Storage: how-to/garbage-collection.md
       - Maintenance:
-          - Migrate to 2.0: how-to/migrate-to-v20.md
+          - Migrate to 2.x: how-to/migrate-to-v20.md
           - Alter Tables: how-to/alter-tables.md
           - Backup and Restore: how-to/backup-restore.md
       - Testing:
diff --git a/src/how-to/migrate-to-v20.md b/src/how-to/migrate-to-v20.md
index 07839ccc..b88b0315 100644
--- a/src/how-to/migrate-to-v20.md
+++ b/src/how-to/migrate-to-v20.md
@@ -1,10 +1,27 @@
-# Migrate to DataJoint 2.0
+# Migrate to DataJoint 2.x
 
-Upgrade existing pipelines from legacy DataJoint (pre-2.0) to DataJoint 2.0+.
+Upgrade existing pipelines from legacy DataJoint (the pre-2.0 `0.x` series)
+directly to the latest DataJoint 2.x — currently **2.3**.
 
 > **This guide is optimized for AI coding assistants.** Point your AI agent at this
 > document and it will execute the migration with your oversight.
 
+!!! tip "Which version do I migrate to?"
+
+    Migrate **straight to the latest 2.x release** (currently 2.3) — there is no
+    need to step through 2.0 → 2.1 → 2.2 → 2.3. A single upgrade takes a `0.x`
+    pipeline all the way to 2.3.
+
+    Everything this guide calls "2.0" is the **migration surface** — the type
+    system, explicit codecs, and unified `stores` introduced in 2.0. Later
+    releases build on it without adding migration steps: **2.1** added the
+    PostgreSQL backend and configurable diagram layout, **2.2** added the jobs
+    layer and diagram operations, and **2.3** added the upstream/provenance API.
+    Installing the latest release gives you all of them.
+
+    Complete the migration while on **2.3 or earlier**: the `datajoint.migrate`
+    helper is scheduled for removal in 2.4/2.5.
+
 !!! warning "Temporary module"
 
     The `datajoint.migrate` module is provided temporarily to assist with migration and is scheduled for removal in DataJoint 2.4 or 2.5. We recommend completing your migration while on DataJoint 2.3 or earlier.