From febe069c6e2860e82cb2c01766768c14af58c503 Mon Sep 17 00:00:00 2001
From: oppiliappan <me@oppi.li>
Date: Mon, 8 Sep 2025 14:39:10 +0100
Subject: [PATCH] docs: write upgrade guide for v1.8.x

merge all migration guides into one doc

Signed-off-by: oppiliappan <me@oppi.li>
---
 appview/pages/templates/banner.html           |  2 +-
 .../knot-1.7.0.md => migrations.md}           | 21 ++++++++++++++++---
 2 files changed, 19 insertions(+), 4 deletions(-)
 rename docs/{migrations/knot-1.7.0.md => migrations.md} (66%)

diff --git a/appview/pages/templates/banner.html b/appview/pages/templates/banner.html
index 16de5a4f..d9bdda16 100644
--- a/appview/pages/templates/banner.html
+++ b/appview/pages/templates/banner.html
@@ -30,7 +30,7 @@
     <div class="mx-6">
       These services may not be fully accessible until upgraded.
       <a class="underline text-red-800 dark:text-red-200"
-        href="https://tangled.sh/@tangled.sh/core/tree/master/docs/migrations/">
+        href="https://tangled.sh/@tangled.sh/core/tree/master/docs/migrations.md">
         Click to read the upgrade guide</a>.
     </div>
   </details>
diff --git a/docs/migrations/knot-1.7.0.md b/docs/migrations.md
similarity index 66%
rename from docs/migrations/knot-1.7.0.md
rename to docs/migrations.md
index 629a3671..41b97004 100644
--- a/docs/migrations/knot-1.7.0.md
+++ b/docs/migrations.md
@@ -1,4 +1,20 @@
-# Upgrading from v1.7.0
+# Migrations
+
+This document is laid out in reverse-chronological order.
+Newer migration guides are listed first, and older guides
+are further down the page.
+
+## Upgrading from v1.8.x
+
+After v1.8.2, the HTTP API for knots has been deprecated and
+replaced with XRPC. Repositories on outdated knots will not
+be viewable from the appview. Upgrading is straightforward:
+
+- Upgrade to latest tag (v1.9.0 or above)
+- Head to the [knot dashboard](https://tangled.sh/knots) and
+  hit the "retry" button to verify your knot
+
+## Upgrading from v1.7.x
 
 After v1.7.0, knot secrets have been deprecated. You no
 longer need a secret from the appview to run a knot. All
@@ -19,8 +35,6 @@ Upgrading is quite easy, in essence:
   hit the "retry" button to verify your knot. This simply
   writes a `sh.tangled.knot` record to your PDS.
 
-## Nix
-
 If you use the nix module, simply bump the flake to the
 latest revision, and change your config block like so:
 
@@ -33,3 +47,4 @@ latest revision, and change your config block like so:
    };
  };
 ```
+
-- 
2.51.2