Document Elasticsearch migrations must be finished before major upgrade

This is the first step to making it clear to operators about what they
need to check before proceeding with a major version upgrade as well as
hopefully helping them debug and fix any problems before proceeding.

We are also going to be removing the migration code from previous
versions in the major version upgrade so it's very important the
migration completes before the upgrade otherwise it will just fail as
it will be a blank migration.

doc/integration/elasticsearch.md

@@ -402,6 +402,15 @@ debug why the migration was halted and make any changes before retrying the migr
 fixed the cause of the failure, click "Retry migration", and the migration will be scheduled to be retried
 in the background.
 
+### All migrations must be finished before doing a major upgrade
+
+Before doing a major version upgrade of GitLab you should have completed all
+migrations that exist up until the latest minor version before that major
+version. If you have halted migrations these will need to be resolved and
+[retried](#retry-a-halted-migration) before proceeding with a major version
+upgrade. Read more about [upgrading to a new major
+version](../update/index.md#upgrading-to-a-new-major-version).
+
 ## GitLab Advanced Search Rake tasks
 
 Rake tasks are available to:

doc/update/index.md

@@ -143,9 +143,11 @@ pending_job_classes.each { |job_class| Gitlab::BackgroundMigration.steal(job_cla
 This section is only applicable if you have enabled the [Elasticsearch
 integration](../integration/elasticsearch.md).
 
-Certain major releases might require [Elasticsearch
+Major releases require all [Elasticsearch
 migrations](../integration/elasticsearch.md#background-migrations) to be
-finished. You can find pending migrations by running the following command:
+finished from the most recent minor release in your current version before the
+major version upgrade. You can find pending migrations by running the following
+command:
 
 **For Omnibus installations**
 
@@ -208,6 +210,13 @@ It's also important to ensure that any background migrations have been fully com
 before upgrading to a new major version. To see the current size of the `background_migration` queue,
 [Check for background migrations before upgrading](#checking-for-background-migrations-before-upgrading).
 
+If you have enabled the [Elasticsearch
+integration](../integration/elasticsearch.md) then you will also need to ensure
+all Elasticsearch migrations are completed in the last minor version within
+your current version. Be sure to [check for pending Elasticsearch
+migrations](#checking-for-pending-elasticsearch-migrations) before proceeding
+with the major version upgrade.
+
 If your GitLab instance has any runners associated with it, it is very
 important to upgrade GitLab Runner to match the GitLab minor version that was
 upgraded to. This is to ensure [compatibility with GitLab versions](https://docs.gitlab.com/runner/#compatibility-with-gitlab-versions).