Skip to content

Backport version doc corrections for a backported FF change

Why is this backport needed (background and context)

https://gitlab.com/gitlab-org/release/tasks/-/issues/11141+ contains backport fixes for a change originally marked as a deprecation in 17.0. Due to a SIRT issue we later made the decision to first backport FF enablement for GitLab 16.10, 16.11 and 17.0. As the change needed to be coupled with additional fixes from other teams, 16.10 fell out of maintenance policy and the backports for only 16.11 and 17.0 were merged for a later patch release (intended to go out on 26th June) and the patch release versions need to be corrected.

@eread identified that the version numbers referred to in the docs were now incorrect, as backports are part of a later release. The linked MRs are to correct these docs.

Get the approval of TW Leadership

The person requesting the backport does this step.

If the backport is for a version older than the latest stable branch, ask Technical Writing Leadership for approval:

  • Mention TW Leadership in a comment in this issue and wait for their approval:

    @gitlab-org/tw-leadership could I get your approval for this documentation backport?

Create the merge request to backport the change

The person requesting the backport does this step. Requires at least the Developer role on the project that needs the backport.

To backport a change, you will merge your changes into the stable branch of the version where you want the change to occur.

  1. Open a merge request with the backport. The MR should target the stable release branch, for example: 16-11-stable-ee or 17-0-stable-ee. Link the MR to this issue.
  2. If the backport targets the current stable branch, assign to a Technical Writer for review and merge. Usually, the Technical Writer of the relevant group.
  3. If the backport targets any branch other than the latest stable branch, assign the MR to a Technical Writer for review. After the TW approves, ask a release manager to review and merge the change. Mention this issue to them and give them all the context they need.

For the change to appear in docs.gitlab.com, merging to the stable branch is all you need.

For the change to appear under /help, the change needs to be part of a GitLab release. The next time a release manager creates a release, they will include the change in the release.

Deploy the backport change

A member of the Technical Writing team does this step. Usually, the same Technical Writer who created the merge request.

After the change is backported to a stable branch, the Docker image that holds that version's docs needs to be updated. These Docker images determine the contents that are displayed when you select the Version drop-down list on the upper-right corner of the docs site.

  1. Run a new pipeline in gitlab-docs. Choose the branch name that matches the stable version, for example 15.11 or 16.0.

If the backport change was made to one of the last three stable branches, you need to update the main docs site:

  1. After the pipeline finishes and the Docker image is updated, go to the pipeline schedules and run the Build docker images manually schedule.
  2. Open the Build docker images pipeline you just started, find the image:docs-latest job, and start it manually.
  3. When the image:docs-latest job is done, run a new pipeline that targets the main branch.
  4. After the pipeline finishes, go to https://docs.gitlab.com and verify that the changes are available for the respective version.

If the backport change was made to a version other than the last three stable branches, you need to update the docs archives site:

  1. Run a new pipeline in gitlab-docs-archives.
  2. After the pipeline finishes, go to https://archives.docs.gitlab.com and verify that the changes are available for the respective version.
Edited by Jon Glassman