Update the update guides for background migrations

The introduction of background migrations means some of our requirements
for online upgrades have to be adjusted / clarified.

See https://gitlab.com/gitlab-org/gitlab-ce/issues/35939 for more
information.

1 files changed, 9 insertions, 0 deletions

diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md
index e67db9ff142..f83a60e49e8 100644
--- a/doc/development/background_migrations.md
+++ b/doc/development/background_migrations.md
@@ -7,6 +7,11 @@ storing data in a single JSON column the data is stored in a separate table.
 
 ## When To Use Background Migrations
 
+>**Note:**
+When adding background migrations _you must_ make sure they are announced in the
+monthly release post along with an estimate of how long it will take to complete
+the migrations.
+
 In the vast majority of cases you will want to use a regular Rails migration
 instead. Background migrations should _only_ be used when migrating _data_ in
 tables that have so many rows this process would take hours when performed in a
@@ -91,6 +96,10 @@ BackgroundMigrationWorker.perform_bulk_in(5.minutes, jobs)
 
 ## Cleaning Up
 
+>**Note:**
+Cleaning up any remaining background migrations _must_ be done in either a major
+or minor release, you _must not_ do this in a patch release.
+
 Because background migrations can take a long time you can't immediately clean
 things up after scheduling them. For example, you can't drop a column that's
 used in the migration process as this would cause jobs to fail. This means that