Add more detail to cleanup steps for background migrations

1. We can't just steal from the queue, in case there was a problem with Sidekiq.
2. We need to consider import / export.

1 files changed, 12 insertions, 3 deletions

diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md
index fc1b202b5eb..ce69694ab6a 100644
--- a/doc/development/background_migrations.md
+++ b/doc/development/background_migrations.md
@@ -133,11 +133,19 @@ roughly be as follows:
 1. Release B:
   1. Deploy code so that the application starts using the new column and stops
      scheduling jobs for newly created data.
-  1. In a post-deployment migration you'll need to ensure no jobs remain. To do
-     so you can use `Gitlab::BackgroundMigration.steal` to process any remaining
-     jobs before continuing.
+  1. In a post-deployment migration you'll need to ensure no jobs remain.
+     1. Use `Gitlab::BackgroundMigration.steal` to process any remaining
+        jobs in Sidekiq.
+     1. Reschedule the migration to be run directly (i.e. not through Sidekiq)
+        on any rows that weren't migrated by Sidekiq. This can happen if, for
+        instance, Sidekiq received a SIGKILL, or if a particular batch failed
+        enough times to be marked as dead.
   1. Remove the old column.
 
+This may also require a bump to the [import/export version][import-export], if
+importing a project from a prior version of GitLab requires the data to be in
+the new format.
+
 ## Example
 
 To explain all this, let's use the following example: the table `services` has a
@@ -296,3 +304,4 @@ for more details.
 [migrations-readme]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/spec/migrations/README.md
 [issue-rspec-hooks]: https://gitlab.com/gitlab-org/gitlab-ce/issues/35351
 [reliable-sidekiq]: https://gitlab.com/gitlab-org/gitlab-ce/issues/36791
+[import-export]: ../user/project/settings/import_export.md