# Tasks for all releases Documentation [for handling the docs release](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/doc/releases.md) is available. > [!note] 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 17.2, the stable branch is `17.2`. The release dates for upcoming releases are listed in the handbook: <https://handbook.gitlab.com/handbook/engineering/releases/monthly-releases/#monthly-release-schedule> ## Release week During the week of the release (usually on Monday): 1. [x] Ensure required tools are installed and up-to-date. In the root path of the `docs-gitlab-com` repository: - Update your local clone: ```shell make update ``` - Install and update all project dependencies: ```shell make setup ``` - Ensure you're [authenticated](https://gitlab.com/gitlab-org/cli/-/blob/main/README.md#oauth-gitlabcom) with `glab`: ```shell $ glab auth status gitlab.com ✓ Logged in to gitlab.com as <username> (<$HOME>/.config/glab-cli/config.yml) ✓ Git operations for gitlab.com configured to use ssh protocol. ✓ API calls for gitlab.com are made over https protocol. ✓ REST API Endpoint: https://gitlab.com/api/v4/ ✓ GraphQL Endpoint: https://gitlab.com/api/graphql/ ✓ Token: ************************** ``` 1. [x] In this issue, create separate comment threads for the retrospective and add items as they appear: ```markdown ## :construction: Notes from release steps: ## :+1: What went well this release? ## :-1: What didn't go well this release? ## :chart_with_upwards_trend: What can we improve going forward? ``` 1. [x] In the root path of the `docs-gitlab-com` repository, use the [`create-archive-branch`](/doc/releases.md#make-create-archive-branch) Make target to add older docs versions to the [`gitlab-docs-archives`](https://gitlab.com/gitlab-org/gitlab-docs-archives) repository. Save a copy of the command output. ```shell make create-archive-branch ``` - [x] Comment in the `Notes from release steps:` comment thread ([example](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/work_items/567#note_3085501697)) and: - Paste the output of the `make create-archive-branch` command, even if it appears successful. - Paste a link to the related pipeline. > [!note] > If you get a `Branch already exists` error, skip to the next step. Do NOT create a merge request for this. The changes are deployed after a few minutes. The release number shown in the script is an older release. For example, if the release version is GitLab 18.0, the command deploys to: `archives.docs.gitlab.com/17.9/`. You can visit `https://archives.docs.gitlab.com/<version>` to verify. 1. [x] [Complete these steps](https://docs.gitlab.com/development/documentation/release_notes/#technical-writer-release-day-process). This process involves creating two MRs. ## Release day These steps take approximately two hours to complete, depending on fixes and pipeline durations. On Thursday (or Friday depending on time zone): 1. [x] After the release post is live, check the #release-post and #release-post-prep channels for any late submissions under review. Wait for all late follow-up updates to be merged to the docs before moving to the next step. The stable branch should represent the final release state. 1. [x] Update your clone of the `docs-gitlab-com` repository. In the root path of the repository: ```shell make update ``` 1. [x] In the root path of the `docs-gitlab-com` repository, use the [`create-stable-branch`](/doc/releases.md#make-create-stable-branch) Make target to create the stable branch by replacing `X.Y` with the new version. Save a copy of the command output. ```shell make create-stable-branch VERSION=X.Y ``` Creating the stable branch on the release day is ideal, though this might not always be possible depending on your time zone. [Issue 248](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/issues/248) exists to automate stable branch creation. - [x] Comment in the `Notes from release steps:` comment thread ([example](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/work_items/567#note_3085501697)) and: - Paste the output of the `make create-stable-branch` command, even if it appears successful. - Paste a link to the related pipeline. - To track the progress of the stable branch pipeline, go to the [pipelines list](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/pipelines), find the pipeline and select it so you can see the individual jobs. - The `test:check_global_nav_entries` job will fail if a page was added to `navigation.yaml` but did not make the cut-off in `gitlab` for this release. If this happens: 1. In your local environment, pull all the latest changes, then check out the release branch. 1. Remove any offending links in the navigation file. 1. Push your change directly back to the release branch. You do not need to create an MR. 1. Add a comment to the `Notes from release steps:` thread to note which entries you fixed and share a link to the new pipeline. - When the stable branch pipeline completes, the new version will be available at `docs.gitlab.com/X.Y`. Verify that the new release is functional, then proceed to the next step. 1. [x] In the root path of the `docs-gitlab-com` repository, use the [`create-release-merge-request`](/doc/releases.md#make-create-release-merge-request) Make target to create the release merge request by replacing `X.Y` with the new version. Save a copy of the command output. This merge request updates the version dropdown list for all online versions: ```shell make create-release-merge-request VERSION=X.Y ``` 1. [x] Comment in the `Notes from release steps:` comment thread ([example](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/work_items/567#note_3085501697)) and: - Paste the output of the `make create-release-merge-request` command, even if it appears successful. - Paste a link to the related MR. 1. [x] Verify that the merge request: - Has the `~release` label. - Includes only the following in the **Changes** tab: - `.gitlab-ci.yml` - `content/versions.json` 1. [x] When the merge request's pipeline has passed, ask in Slack in `#tw-team` for someone to review and merge the release merge request for you. 1. [x] 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 version dropdown list. Note that it may take up to 5 minutes for the deployed changes to appear on the website due to caching. The next release version appears as the default version in `docs.gitlab.com`. 1. [x] Check the version dropdown list to ensure all versions of the docs are visible and their version dropdown lists 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 GitLab 15.6 and later. Earlier versions might have broken links in the version dropdown list. This will eventually be resolved as the earlier versions are phased out. 1. [x] Have someone merge the two MRs to create the next version's release post markdown document and update the left nav. 1. [x] Share the following message in the `#tw-team` channel: ```plaintext :mega: The docs <version> release is complete. If you have any feedback about this release, add it to the retro thread in <this issue>. ``` ## Post-deployment checklist After the docs release is complete: 1. [x] **Major releases only.** Update [`OutdatedVersions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab_base/OutdatedVersions.yml) with the latest outdated version. 1. [x] Improve [this checklist](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/.gitlab/issue_templates/release.md). 1. [ ] [Create a release issue](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/issues/new?issue%5Btitle%5D=docs.gitlab.com+release+XX.ZZ+%28month%2C+YYYY%29&issuable_template=Release) for the next release, and assign it to the next TW in the [schedule](https://handbook.gitlab.com/handbook/product/ux/technical-writing/#schedule). ## Helpful links - [Troubleshooting info](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/doc/releases.md#troubleshooting) - [List of upcoming assignees for overall release post](https://handbook.gitlab.com/handbook/marketing/blog/release-posts/managers/) - [Internal docs for handling the docs release](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/doc/releases.md)