[docs] Info rescheduling background migrationsbvl-fix-concurrent-fork-network-migrations

1 files changed, 12 insertions, 0 deletions

diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md
index af2026c483e..fc1b202b5eb 100644
--- a/doc/development/background_migrations.md
+++ b/doc/development/background_migrations.md
@@ -94,6 +94,18 @@ jobs = [['BackgroundMigrationClassName', [1]],
 BackgroundMigrationWorker.bulk_perform_in(5.minutes, jobs)
 ```
 
+### Rescheduling background migrations
+
+If one of the background migrations contains a bug that is fixed in a patch
+release, the background migration needs to be rescheduled so the migration would
+be repeated on systems that already performed the initial migration.
+
+When you reschedule the background migration, make sure to turn the original
+scheduling into a no-op by clearing up the `#up` and `#down` methods of the
+migration performing the scheduling. Otherwise the background migration would be
+scheduled multiple times on systems that are upgrading multiple patch releases at
+once.
+
 ## Cleaning Up
 
 >**Note:**