Document ID Unification migration plan

Co-authored-by: Drew DeVault <sir@cmpwn.com>

1 files changed, 46 insertions, 0 deletions

diff --git a/ops/id-unification.md b/ops/id-unification.md
new file mode 100644
index 0000000..b0a7c65
--- /dev/null
+++ b/ops/id-unification.md
@@ -0,0 +1,46 @@
+---
+title: ID unification migration plan
+---
+
+**DRAFT**
+
+A coming update to SourceHut's internal design calls for the values of the ID
+columns in our databases to be made uniform. Each database (e.g. for git, hg,
+builds, etc) maintained its own copy of tables with shared information, sourcing
+updates from meta.sr.ht via webhooks, but each of these rows had an ID specific
+to each database. This change will make these IDs uniform across all services in
+preparation for linking our services more tightly together through GraphQL
+Federation.
+
+This document outlines the extra steps required to perform this upgrade for
+third-party instances.
+
+## Upgrade process
+
+1. Disable automatic migrations
+1. Upgrade meta.sr.ht and ensure that the meta.sr.ht GraphQL API is online
+1. Upgrade remaining services
+1. Run `$service-migrate upgrade head` (e.g. gitsrht-migrate) for each service
+   and monitor the migration progress
+1. Re-enable automatic migrations if desired
+
+## Downgrade process
+
+1. Disable automatic migrations
+1. Downgrade meta.sr.ht
+1. Downgrade remaining services
+1. Run `$service-migrate downgrade $version`, selecting $version from the list
+   below, for each service
+
+## Affected database schema revisions
+
+Last schema revision prior to this change, for reference if downgrading:
+
+- builds.sr.ht: *TODO*
+- git.sr.ht: *TODO*
+- hg.sr.ht: *TODO*
+- hub.sr.ht: *TODO*
+- lists.sr.ht: *TODO*
+- man.sr.ht: *TODO*
+- pages.sr.ht: *TODO*
+- todo.sr.ht: *TODO*