Skip to content

docs.gitlab.com release 16.7 (December, 2023)

16.7 release date: 2023-12-21

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.7, the stable branch is 16.7.

On Monday the week of the release

  1. Cross-link to the main MR for the release post: gitlab-com/www-gitlab-com!131798 (merged)

  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. Create a stable branch and Docker image for the release.

Create a stable branch and Docker image for the release

Note: an issue exists to create the stable branch automatically.

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

    make update

  2. Optional. 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 16.7 for the release is created.
    • A new 16.7.Dockerfile is created and automatically committed.
    • The new branch is pushed.

    After the branch is created, the image:docs-single job runs and creates a new Docker image tagged with the name of the stable branch (for example, see the 15.6 release pipeline). When the job finishes, confirm the Docker image has been created. Go to the registry environment at https://gitlab.com/gitlab-org/gitlab-docs/-/environments/folders/registry and confirm the image is listed.

    In case the pipeline fails, see the troubleshooting section.

You can continue onto the next process immediately, or wait for the release post.

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 after all upstream stable branches have been created. 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.7".

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

  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, 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 documentation version dropdown.

  6. Check all published versions of the docs to ensure they are visible and that their version menus have the latest versions.

  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 successful:

  1. Create a release issue for the next release, and assign it to the TW who completed the release post structural check for the previous milestone.
  2. Major releases only. Update OutdatedVersions.yml with the newly-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 Phillip Wells