Standardize upgrade path information

Summary

Currently, GitLab maintains the upgrade path information in several places, few known locations are:

• Omnibus: Make 16.3 minimum required version to upgrade t... (omnibus-gitlab#8103 - closed)
• Chart: Make 16.3/7.3 minimum required version to upgra... (gitlab-org/charts/gitlab#4895 - closed)
• Update Gitlab::Database::MIN_SCHEMA_GITLAB_VERSION in lib/gitlab/database.rb to the new required stop versions. Do not change Gitlab::Database::MIN_SCHEMA_VERSION.
• Upgrade-path project: https://gitlab.com/gitlab-com/support/toolbox/upgrade-path
• GitLab docs: https://docs.gitlab.com/ee/update/#upgrade-paths

This potentially cause effort duplication and inconsistency.

Acceptance criteria

• Decide the SSoT location for the information
• Update all projects to refer to the SSoT
  • This will be done by other issues:

Solution proposal

Initial thought

• One possible solution from #415993 (comment 1489427501) (credit to @Alexand and @mattkasa)

We can have required_stops.yaml on gitlab-org/gitlab as a SSOT. To avoid the situation where the users have to do outbound API requests during installs to check the required stops, we can embed them into the Chart and Omnibus package during build/release phase of our CI.

We only need to know the latest required stop before the desired upgrade-to version.

For Omnibus,

We can fetch the latest required stop before the version we're building, then inject it into the preinst script as a new variable, LAST_REQUIRED_STOP=X.Y.Z: https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/cf6d0013fcc8d2fa820cd840c280ead6fe0b1e07/config/templates/package-scripts/preinst.erb#L7. The the preinst script can fail if the current version is lower than the last required stop, and we can guide the user to check the list of required stops.

For Chart,

we already have a pre-upgrade Helm hook that does some min version checks for minimum chart and Postgres version. We could extend that to also check for LAST_REQUIRED_STOP. We could also inject the LAST_REQUIRED_STOP from CI when we're releasing the Chart.

Direction we decided

Instead of using the LAST_REQUIRED_STOP we decided to make use of the already existing MIN_VERSION.

Instead of shipping the version within package, we initially decided to use the release tools to update these versions in the chart and omnibus. Example implementation: Maintain upgrade stop for Omnibus (release-tools!2925 - merged)