Skip to content

docs.gitlab.com release 17.2 (July, 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 17.2, the stable branch is 17.2.

On Monday the week of the release

  1. Cross-link to the main MR for the release post: Release post - GitLab 17.2 (gitlab-com/www-gitlab-com!135175 - merged) (Need help finding the MR?)

  2. 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?

  3. Add the version to be removed from the version dropdown list to the docs archives. This would be the earlier version from the last_minor hash in content/versions.json.

    1. 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}

    2. Create the merge request in gitlab-org/gitlab-docs-archives and merge it.

  4. Create a stable branch and Docker image for the release.

Create a stable branch and Docker image for the release

  1. In the root path of the gitlab-docs repository:

    • Update your local clone:

      make update

    • Install all project dependencies:

      make setup

  2. To practice running the task and check the process, run the Rake task in dry run mode:

    DRY_RUN=true make create-stable-branch

  3. 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.
    • Do not create an MR for this step. This file is only used when a stable branch pipeline is run.

On the Thursday of the release, or the day after

After the release post is live, or the day after:

  1. Check that the stable branches that correspond with the release are present:

    If not, you cannot proceed to the next step, so you'll have to wait.

  2. Run a new pipeline targeting the docs stable branch. 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 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, in the Filter pipelines text box, select the Branch name filter, then manually enter the current stable branch. For example, Branch name = 17.2.

  3. Create a docs.gitlab.com release merge request, which updates the version dropdown list for all online versions, updates the archives list, and adds the release to the Docker configuration:

    1. In the root path of the gitlab-docs repository, update your local clone:

      make update

    2. Create a branch release-X-Y. For example:

      git checkout -b release-17-2

    3. In content/versions.json, update the lists of versions to reflect the release in the version dropdown list:

      • Set next to the version number of the next release. For example, if you're releasing 17.2, set next to 17.3.
      • Set current to the version number of the release you're releasing. For example, if you're releasing 17.2, set current to 17.2.
      • Set last_minor to the last two most recent minor releases. For example, if you're releasing 17.2, set last_minor to 17.1 and 17.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 releasing 17.2, ensure last_major are 16.11 and 15.11.

      As a complete example, the content/versions.json file for the 17.2 release is:

      [
  {
    "next": "17.3",
    "current": "17.2",
    "last_minor": ["17.1", "17.0"],
    "last_major": ["16.11", "15.11"]
  }
]

    4. In latest.Dockerfile, remove the earliest version, then add the latest version to the top of the list.

    5. In .gitlab/ci/docker-images.gitlab-ci.yml, under the test:image:docs-single and test:image:docs-single-lunrjs jobs, change the GITLAB_VERSION variable to the version number of the release you're releasing.

    6. Commit and push to create the merge request (but without running any lefhook tests). For example:

      git add .
git commit -m "Docs release 17.2"
LEFTHOOK=0 git push origin release-17-2

    7. Create the merge request, then:

      • Add the ~release label.
      • Verify that the Changes tab includes the following files:
        • .gitlab/ci/docker-images.gitlab-ci.yml
        • content/versions.json
        • latest.Dockerfile

  4. Deploy the versions:

    1. Merge the docs release merge request.
    2. Go to the scheduled pipelines page and run the Build Docker images manually pipeline.
    3. In the scheduled pipeline you just started, wait for the test:image:docs-latest job to finish, then manually run the image:docs-latest job that builds the :latest Docker image.
    4. When the image:docs-latest job is complete, go back to the scheduled pipelines page and run the Build docs.gitlab.com every hour scheduled pipeline.

  5. 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.

  6. 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.

  7. 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 complete:

  1. 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.
  2. Major releases only. Update OutdatedVersions.yml with the latest outdated version.
  3. 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.

Helpful links

Edited by Amy Qualls