docs.gitlab.com release 17.0 (May, 2024)
Tasks for all releases
Documentation for handling the docs release is available.
Prerequisites:
- Make sure you have all the needed tools installed on your system.
Terminology:
The following terms are used throughout this document:
-
Stable branch: This is the branch that matches the GitLab version being released. For example,
for GitLab 16.0, the stable branch is
16.0
.
On Monday the week of the release
-
Cross-link to the main MR for the release post: <add link here>
(Need help finding the MR?) -
In this issue, create separate threads for the retrospective, and add items as they appear: ## :+1: What went well this release? ## :-1: What didn't go well this release? ## :chart_with_upwards_trend: What can we improve going forward?
-
Add the version to be removed from the dropdown to the docs archives. This would be the oldest version from the last_minor
hash inversions.json
.-
Edit
archives.Dockerfile
and add a new line at the end of the file with the archived version. It should read like:COPY --from=registry.gitlab.com/gitlab-org/gitlab-docs/archives:<version> ${TARGET} ${TARGET}
-
Create the merge request in
gitlab-org/gitlab-docs-archives
and merge it.
-
Create a stable branch and Docker image for the release
Note: an issue exists to create the stable branch automatically.
-
In the root path of the gitlab-docs
repository:-
Update your local clone:
make update
-
Install all project dependencies:
make setup
-
-
To practice running the task and check the process, run the Rake task in dry run mode: DRY_RUN=true make create-stable-branch
-
Create the stable branch: make create-stable-branch
- A branch
X.Y
for the release is created. - A new
X.Y.Dockerfile
is created and automatically committed. - The new branch is pushed.
- A branch
On the Thursday of the release, or the day after
After the release post is live, or the day after:
-
Check that the stable branches that correspond with the release are present:
-
gitlab
: https://gitlab.com/gitlab-org/gitlab/-/branches?state=all&sort=updated_desc&search=stable-ee -
gitlab-runner
: https://gitlab.com/gitlab-org/gitlab-runner/-/branches?state=all&sort=updated_desc&search=-stable -
omnibus-gitlab
: https://gitlab.com/gitlab-org/omnibus-gitlab/-/branches?state=all&sort=updated_desc&search=-stable -
charts/gitlab
: https://gitlab.com/gitlab-org/charts/gitlab/-/branches?state=all&sort=updated_desc&search=-stable (Version number is 9 lower thangitlab
release, so GitLab 16.X = Charts 7.X)
If not, you cannot proceed to the next step, so you'll have to wait.
-
-
Run a new pipeline targeting the docs stable branch after all upstream stable branches have been created. When the pipeline runs, the image:docs-single
job builds a new Docker image tagged with the name of the stable branch containing all the versioned documentation (for example, see the 15.6 release pipeline).Verify that the pipeline for the stable branch (filter by branch) has passed and created a Docker image tagged with the release version. (If it fails, how do I fix it?)
- To filter the list of pipelines to the stable branch, select the Branch name filter then manually input the stable branch's name. For example, "Branch name = 16.0".
-
Create a docs.gitlab.com release merge request, which updates the version dropdown menu for all online versions, updates the archives list, and adds the release to the Docker configuration:
-
In the root path of the gitlab-docs
repository, update your local clone:make update
-
Create a branch release-X-Y
. For example:git checkout -b release-15-0
-
Edit content/versions.json
and update the lists of versions to reflect the new release in the Versions menu:- Set
next
to the version number of the next release. For example, if you're releasing15.2
, setnext
to15.3
. - Set
current
to the version number of the release you're releasing. For example, if you're releasing15.2
, setcurrent
to15.2
. - Set
last_minor
to the last two most recent minor releases. For example, if you're releasing15.2
, setlast_minor
to15.1
and15.0
. - Ensure
last_major
is set to the two most recent major versions. Do not include the current major version. For example, if you're releasing15.2
, ensurelast_major
is14.10
and13.12
.
As a complete example, the
content/versions.json
file for the15.2
release is:[ { "next": "15.3", "current": "15.2", "last_minor": ["15.1", "15.0"], "last_major": ["14.10", "13.12"] } ]
- Set
-
Edit latest.Dockerfile
by removing the oldest version, and then adding the newest version to the top of the list. -
Open .gitlab/ci/docker-images.gitlab-ci.yml
and edit thetest:image:docs-single:
job to change theGITLAB_VERSION
variable. Set it to the version number of the release you're releasing. -
Commit and push to create the merge request (but without running any lefhook
tests). For example:git add .gitlab/ci/docker-images.gitlab-ci.yml content/versions.json latest.Dockerfile git commit -m "Docs release 15.0" LEFTHOOK=0 git push origin release-15-0
-
Create the merge request, then: - Add the
~release
label. - Mark the merge request as Draft.
- Verify that the Changes tab includes the following files:
.gitlab/ci/docker-images.gitlab-ci.yml
content/versions.json
latest.Dockerfile
- Add the
-
-
Deploy the versions:
-
Mark the docs release merge request as ready, and merge it. -
Go to the scheduled pipelines page and run the Build Docker images manually
pipeline. -
In the scheduled pipeline you just started, wait for the test:image:docs-latest
job to finish, then manually run theimage:docs-latest
job that builds the:latest
Docker image. -
When the image:docs-latest
job is complete, run theBuild docs.gitlab.com every hour
scheduled pipeline.
-
-
After the deployment completes, open docs.gitlab.com
in a browser. Confirm both the latest version and the correct pre-release version are listed in the documentation version dropdown. -
Check all versions of the docs in the version dropdown to ensure they are visible and that their version menus have the expected versions. - Versions hosted on
docs.gitlab.com
should show the same version options as the pre-release site. - Versions hosted on
archives.docs.gitlab.com
should only show their own version and a link back to the archives page.- This applies to v15.6 and newer; older versions may have broken links in the dropdown. This will eventually be resolved as the older versions are phased out.
- Versions hosted on
-
Share the following message in the #tw-team
channel::mega: The docs <version> release is complete. If you have any feedback about this release, add it to the retro thread in <this issue>.
After the docs release is successful:
-
Create a release issue for the next release, and assign it to the TW who completed the release post structural check for the current milestone. -
Major releases only. Update OutdatedVersions.yml
with the newly-outdated version. -
Improve this checklist. Continue moving steps from releases.md
to here until the issue template is the single source of truth and the documentation provides extra information.