FY24Q3 TW OKR: Consolidate version-specific upgrade steps for consistency and findability => 100%
When upgrading GitLab, users must follow version-specific instructions for each minor version of GitLab, and according to their type of installation. These instructions are scattered throughout the docs in an inconsistent manner, making them hard to follow and find.
High-level KR: https://gitlab.com/gitlab-com/gitlab-OKRs/-/work_items/3666
Original epic that documents this issue in more detail: &9581
Current locations of upgrade docs:
- Generic: https://docs.gitlab.com/ee/update/#version-specific-upgrading-instructions
- Linux package (Omnibus): https://docs.gitlab.com/ee/update/package/#version-specific-changes
- Geo: https://docs.gitlab.com/ee/administration/geo/replication/version_specific_upgrades.html
This KR will merge information from these three separate locations to single version-specific pages (similar to the current Omnibus structure).
The Upgrading GitLab page is one of the highest-viewed pages on the docs site--one of the top 20 pages by page views. By consolidating the version-specific upgrade information, we will improve the organization and findability of the upgrade docs.
Out of scope
- This is a lift & shift exercise. We will not review the content for language/style.
- (TBD) Charts version-specific information.
Resources
Create a page for each major version using the following template:
# GitLab X changes **(FREE SELF)**
This page contains upgrade information for minor and patch versions of GitLab X. Ensure you review these instructions for:
- Your installation type.
- All versions between your current version and your target version.
For more information about upgrading GitLab Helm Chart, see [the release notes for X.0](https://docs.gitlab.com/charts/releases/X_0.html).
## X.Y
- <Include general upgrade notes and issues here.>
- ...
### Linux package installations
- ...
- ...
### Self-compiled installations
- ...
- ...
### Geo installations
- ...
- ...
At the end of this effort, the left nav will go from this structure:
- Upgrade GitLab
- Plan an upgrade
- Background migrations
- Upgrade a Linux package instance
- Convert to Linux package (Omnibus)
- Convert to Enterprise Edition
- Package signatures
- Gitlab 16 changes
- Gitlab 15 changes
- Gitlab 14 changes
- Downgrade
- Upgrade self-compiled instance
- ...
To this structure:
- Upgrade GitLab
- Plan an upgrade
- Background migrations
- Upgrade a Linux package instance
- Convert to Linux package (Omnibus)
- Convert to Enterprise Edition
- Package signatures
- Downgrade
- Upgrade a self-compiled instance
- Gitlab 16 changes
- Gitlab 15 changes
- Gitlab 14 changes
- ...
Other references
- https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#how-to-document-different-installation-methods
- https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#use-tabs-to-describe-a-self-managed-configuration-procedure
Steps
GitLab 16
-
Create file in doc/update/versions
using the template. Name the filegitlab_16_changes.md
. -
Migrate relevant content from https://docs.gitlab.com/ee/update/#version-specific-upgrading-instructions to the relevant version heading. -
Move any Geo-specific notes to the Geo
subheading. -
Move any self-compiled notes to the Self-compiled
heading.
-
-
In https://docs.gitlab.com/ee/update/#version-specific-upgrading-instructions, replace moved content with a crosslink to new page. -
Check https://docs.gitlab.com/ee/administration/geo/replication/version_specific_upgrades.html and move any relevant version-specific instructions to the Geo subheading on the new page. Replace with crosslink. -
Move content from https://docs.gitlab.com/omnibus/update/gitlab_16_changes.html to Linux package
subheading on new page. -
Remove https://docs.gitlab.com/omnibus/update/gitlab_16_changes.html and redirect to new page. - Left nav:
-
Remove link to old Linux package (Omnibus) version-specific page. -
Add new version-specific page under Upgrade GitLab
.
-
GitLab 15
-
Create file in doc/update/versions
using the template. Name the filegitlab_15_changes.md
. -
Migrate relevant content from https://docs.gitlab.com/ee/update/#version-specific-upgrading-instructions to the relevant version heading. -
Move any Geo-specific notes to the Geo
subheading. -
Move any self-compiled notes to the Self-compiled
heading.
-
-
In https://docs.gitlab.com/ee/update/#version-specific-upgrading-instructions, replace moved content with a crosslink to new page. -
Check https://docs.gitlab.com/ee/administration/geo/replication/version_specific_upgrades.html and move any relevant version-specific instructions to the Geo subheading on the new page. Replace with crosslink. -
Move content from https://docs.gitlab.com/omnibus/update/gitlab_15_changes.html to Linux package
subheading on new page. -
Remove https://docs.gitlab.com/omnibus/update/gitlab_15_changes.html and redirect to new page. - Left nav:
-
Remove link to old Linux package (Omnibus) version-specific page.. -
Add new version-specific page under Upgrade GitLab
.
-
GitLab 14
-
Create file in doc/update/versions
using the template. Name the filegitlab_14_changes.md
. -
Migrate relevant content from https://docs.gitlab.com/ee/update/#version-specific-upgrading-instructions to the relevant version heading. -
Move any Geo-specific notes to the Geo
subheading. -
Move any self-compiled notes to the Self-compiled
heading.
-
-
In https://docs.gitlab.com/ee/update/#version-specific-upgrading-instructions, replace moved content with a crosslink to new page. -
Check https://docs.gitlab.com/ee/administration/geo/replication/version_specific_upgrades.html and move any relevant version-specific instructions to the Geo subheading on the new page. Replace with crosslink. -
Move content from https://docs.gitlab.com/omnibus/update/gitlab_14_changes.html to Linux package
subheading on new page. -
Remove https://docs.gitlab.com/omnibus/update/gitlab_14_changes.html and redirect to new page. - Left nav:
-
Remove link to old Linux package (Omnibus) version-specific page. -
Add new version-specific page under Upgrade GitLab
.
-
Older versions
-
Remove version-specific notes for GitLab 13 and older from https://docs.gitlab.com/ee/update/#version-specific-upgrading-instructions and add link to doc archives.