Merge branch 'docs-bprescott-upgradepaths207259-20200319' into 'master'

Revise upgrade policy to note 8.12 and Barometer

See merge request gitlab-org/gitlab!27572

doc/policy/maintenance.md

@@ -156,6 +156,15 @@ To ensure these are successful:
 
 For example: `11.11.x` -> `12.0.x` -> `12.8.x`
 
+### Upgrades from old versions
+
+- `8.11.x` and earlier: you might have to upgrade to `8.12.0` specifically before you can
+  upgrade to `8.17.7`. This was [reported in an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/207259).
+- [CI changes prior to version 8.0](https://docs.gitlab.com/omnibus/update/README.html#updating-gitlab-ci-from-prior-540-to-version-714-via-omnibus-gitlab)
+  when it was merged into GitLab.
+- Version specific changes in
+  [the Omnibus documentation](https://docs.gitlab.com/omnibus/update/README.html#version-specific-changes).
+
 ### Example upgrade paths
 
 Please see the table below for some examples:
@@ -165,7 +174,7 @@ Please see the table below for some examples:
 | 9.4.5                 | 8.13.4       | `8.13.4` -> `8.17.7` -> `9.4.5`                          | `8.17.7` is the last version in version `8` |
 | 10.1.4                | 8.13.4       | `8.13.4 -> 8.17.7 -> 9.5.10 -> 10.1.4`                   | `8.17.7` is the last version in version `8`, `9.5.10` is the last version in version `9` |
 | 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.12` -> `12.5.8`            | `11.11.8` is the last version in version `11`. `12.0.x` [is a required step](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23211#note_272842444). |
+| 12.5.10               | 11.3.4       | `11.3.4` -> `11.11.8` -> `12.0.12` -> `12.5.10`            | `11.11.8` is the last version in version `11`. `12.0.x` [is a required step](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23211#note_272842444). |
 | 12.8.5                | 9.2.6       | `9.2.6` -> `9.5.10` -> `10.8.7` -> `11.11.8` -> `12.0.12` -> `12.8.5` | Four intermediate versions are required: the final 9.5, 10.8, 11.11 releases, plus 12.0. |
 
 NOTE: **Note:**
@@ -173,6 +182,21 @@ Instructions for installing a specific version of GitLab or downloading the pack
 
 ## More information
 
+Check [our release posts](https://about.gitlab.com/releases/categories/releases/).
+
+Each month, we publish either a major or minor release of GitLab. At the end
+of those release posts there are three sections to look for: deprecations, important notes,
+and upgrade barometer. These will will draw your attention to:
+
+- Steps you need to perform as part of an upgrade.
+  For example [8.12](https://about.gitlab.com/releases/2016/09/22/gitlab-8-12-released/#upgrade-barometer)
+  required the Elasticsearch index to be recreated. Any older version of GitLab upgrading to 8.12 or higher
+  would require this.
+- Changes to the versions of software we support such as
+  [ceasing support for IE11 in GitLab 13](https://about.gitlab.com/releases/2020/03/22/gitlab-12-9-released/#ending-support-for-internet-explorer-11).
+
+You should check all the major and minor versions you're passing over.
+
 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/).