Merge pull request #36844 from overleaf/em-document-migration-tags

Document the auxiliary and nonblocking migration tags

GitOrigin-RevId: ad16fe6b4f3e13606fff1d18f543cca0c2268ee2

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:

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 => {