diff --git a/docs/source/migrating_to_1.17.rst b/docs/source/migrating_to_1.17.rst
new file mode 100644
index 00000000..66c26ab8
--- /dev/null
+++ b/docs/source/migrating_to_1.17.rst
@@ -0,0 +1,30 @@
+Migrating to Koji 1.17
+======================
+
+..
+  reStructured Text formatted
+
+You should consider the following changes when migrating to 1.17:
+
+DB Updates
+----------
+
+This release some minor schema changes
+
+    * the ``tag_external_repos`` table has a new ``merge_mode`` column
+    * the ``build_target.name`` column is now a TEXT field rather than VARCHAR
+
+As in previous releases, we provide a migration script that updates the
+database.
+
+::
+
+    # psql koji koji  </usr/share/doc/koji/docs/schema-upgrade-1.16-1.17.sql
+
+
+Other changes
+-------------
+
+There are numerous other changes in 1.17 that should not have a direct impact
+on migration. For details see:
+:doc:`release_notes_1.17`
diff --git a/docs/source/migrations.rst b/docs/source/migrations.rst
index a81546e7..397b21c6 100644
--- a/docs/source/migrations.rst
+++ b/docs/source/migrations.rst
@@ -5,6 +5,7 @@ Migrations
 .. toctree::
     :maxdepth: 1
 
+    migrating_to_1.17
     migrating_to_1.16
     migrating_to_1.15
     migrating_to_1.14