From 2bbdc22496f4267b5c08f711782cb7f7d0373154 Mon Sep 17 00:00:00 2001
From: Eric Mc Sween <5454374+emcsween@users.noreply.github.com>
Date: Mon, 24 Aug 2026 07:43:32 -0400
Subject: [PATCH] Merge pull request #36844 from
 overleaf/em-document-migration-tags

Document the auxiliary and nonblocking migration tags

GitOrigin-RevId: ad16fe6b4f3e13606fff1d18f543cca0c2268ee2
---
 tools/migrations/README.md                    | 28 +++++++++++++++++++
 .../lib/20000000000000_template.mjs           |  5 ++++
 2 files changed, 33 insertions(+)

diff --git a/tools/migrations/README.md b/tools/migrations/README.md
index a7bb0dcc7c..ae8487e55a 100644
--- a/tools/migrations/README.md
+++ b/tools/migrations/README.md
@@ -40,6 +40,34 @@ For example, a migration that should run in every environment would be tagged wi
 When invoking east, we specify the relevant tags with the `-t` or `--tags` flag.
 Our adapter will refuse to run if this flag is not set.
 
+### Other tags
+
+Besides the environment tags, two more tags change how a migration is handled:
+
+#### `auxiliary`
+
+Use the `auxiliary` tag when the migration operates on collections that live on the auxiliary Mongo
+cluster (`mongo.auxUrl`). The tag doesn't affect how the migration reaches those collections: the
+handles exported by `lib/mongodb.mjs` already point at whichever cluster holds them, so an
+`auxiliary` migration uses the same `db.<collection>` as any other migration.
+
+What the tag controls is where the adapter records the migration, namely the `migrations` collection
+on the auxiliary cluster. This is what makes a migration that already ran against the main cluster,
+before the auxiliary cluster was provisioned, run again once the auxiliary cluster is configured.
+When no auxiliary cluster is configured, the main cluster holds both the collections and the
+execution record.
+
+#### `nonblocking`
+
+Deployments are gated on pending migrations: the `scripts/check_blocking.mjs` predeploy hook fails
+the rollout when a migration the released image expects hasn't been applied yet. Tagging a migration
+`nonblocking` exempts it from that gate, so the deployment goes through even while the migration is
+still pending.
+
+Use it for migrations the new code doesn't depend on — for instance adding an index that only
+improves performance, or a data cleanup that can trail the deploy. Anything the released code needs
+in place to work correctly should stay blocking.
+
 ### Creating new migrations
 
 To create a new migration, run:
diff --git a/tools/migrations/lib/20000000000000_template.mjs b/tools/migrations/lib/20000000000000_template.mjs
index 742df1d9e0..44941cb548 100644
--- a/tools/migrations/lib/20000000000000_template.mjs
+++ b/tools/migrations/lib/20000000000000_template.mjs
@@ -2,6 +2,11 @@
 
 import Helpers from './lib/helpers.mjs'
 
+// Environments this migration should run in: 'server-ce', 'server-pro', 'saas'.
+// Two extra tags are also supported:
+//   'auxiliary'   - the migration operates on collections on the auxiliary Mongo cluster
+//   'nonblocking' - deployments may go through while this migration is pending
+// See the README for details.
 const tags = ['server-ce', 'server-pro', 'saas']
 
 const migrate = async client => {