Merge branch 'docs-background-migrations-check' into 'master'

Documentation to promote checking background migrations

See merge request gitlab-org/gitlab!22559

doc/policy/maintenance.md

@@ -139,6 +139,11 @@ We cannot guarantee that upgrading between major versions will be seamless. As p
 We recommend that you first upgrade to the latest available minor version within
 your major version. By doing this, you can address any deprecation messages
 that could change behavior in the next major release.
+
+It's also important to ensure that any background migrations have been fully completed
+before upgrading to a new major version. To see the current size of the `background_migration` queue,
+[Check for background migrations before upgrading](../update/README.md#checking-for-background-migrations-before-upgrading).
+
 To ensure background migrations are successful, increment by one minor version during the version jump before installing newer releases.
 
 For example: `11.11.x` -> `12.0.x`
@@ -151,9 +156,6 @@ Please see the table below for some examples:
 | 11.3.4                | 8.13.4       | `8.13.4` -> `8.17.7` -> `9.5.10` -> `10.8.7` -> `11.3.4` | `8.17.7` is the last version in version `8`, `9.5.10` is the last version in version `9`, `10.8.7` is the last version in version `10` |
 | 12.5.8                | 11.3.4       | `11.3.4` -> `11.11.8` -> `12.0.9` -> `12.5.8`            | `11.11.8` is the last version in version `11` |
 
-To check the size of `background_migration` queue and to learn more about background migrations
-see [Upgrading without downtime](../update/README.md#upgrading-without-downtime).
-
 More information about the release procedures can be found in our
 [release documentation](https://gitlab.com/gitlab-org/release/docs). You may also want to read our
 [Responsible Disclosure Policy](https://about.gitlab.com/security/disclosure/).

doc/update/README.md

@@ -69,13 +69,8 @@ before continuing the upgrading procedure. While this won't require downtime
 between upgrading major/minor releases, allowing the background migrations to
 finish. The time necessary to complete these migrations can be reduced by
 increasing the number of Sidekiq workers that can process jobs in the
-`background_migration` queue. To check the size of this queue,
-[start a Rails console session](https://docs.gitlab.com/omnibus/maintenance/#starting-a-rails-console-session)
-and run the command below:
-
-```ruby
-Sidekiq::Queue.new('background_migration').size
-```
+`background_migration` queue. To see the size of this queue,
+[Check for background migrations before upgrading](#checking-for-background-migrations-before-upgrading).
 
 As a rule of thumb, any database smaller than 10 GB won't take too much time to
 upgrade; perhaps an hour at most per minor release. Larger databases however may
@@ -112,6 +107,36 @@ meet the other online upgrade requirements mentioned above.
 
 Steps to [upgrade without downtime][omni-zero-downtime].
 
+## Checking for background migrations before upgrading
+
+Certain major/minor releases may require a set of background migrations to be
+finished. The number of remaining migrations jobs can be found by running the
+following command:
+
+**For Omnibus installations**
+
+```bash
+sudo gitlab-rails runner -e production 'puts Sidekiq::Queue.new("background_migration").size'
+```
+
+**For installations from source**
+
+```
+cd /home/git/gitlab
+sudo -u git -H bundle exec rails runner -e production 'puts Sidekiq::Queue.new("background_migration").size'
+```
+
+## Upgrading to a new major version
+
+Major versions are reserved for backwards incompatible changes. We recommend that
+you first upgrade to the latest available minor version within your major version.
+Please follow the [Upgrade Recommendations](../policy/maintenance.md#upgrade-recommendations)
+to identify the ideal upgrade path.
+
+Before upgrading to a new major version, you should ensure that any background
+migration jobs from previous releases have been completed. The number of remaining
+migrations jobs can be found by running the following command:
+
 ## Upgrading between editions
 
 GitLab comes in two flavors: [Community Edition][ce] which is MIT licensed,

doc/update/upgrading_from_source.md

@@ -23,6 +23,17 @@ guide links by version.
 If you are changing from GitLab Community Edition to GitLab Enterprise Edition, see
 the [Upgrading from CE to EE](upgrading_from_ce_to_ee.md) documentation.
 
+## Upgrading to a new major version
+
+Major versions are reserved for backwards incompatible changes. We recommend that
+you first upgrade to the latest available minor version within your major version.
+Please follow the [Upgrade Recommendations](../policy/maintenance.md#upgrade-recommendations)
+to identify the ideal upgrade path.
+
+Before upgrading to a new major version, you should ensure that any background
+migration jobs from previous releases have been completed. To see the current size of the `background_migration` queue,
+[Check for background migrations before upgrading](README.md#checking-for-background-migrations-before-upgrading).
+
 ## Guidelines for all versions
 
 This section contains all the steps necessary to upgrade Community Edition or