Backport documentation changes

There are two types of backports:

• Current stable release: Any maintainer can backport changes, usually bug fixes but also important documentation changes, into the current stable release. If the milestone in development is 18.7, for example, the most recent stable branch is 18-6-stable-ee.
• Older stable releases: To guarantee the maintenance policy is respected, merging to older stable releases is restricted to release managers.

Backport documentation changes to current stable release

To backport documentation changes to the current stable release:

1. Pull the stable branch, for example 18-6-stable-ee.
2. Make your changes and open an MR. Use the stable branch template.
3. Deploy the changes to the docs site.

You do not need to involve a release manager.

Backport documentation changes to older releases

[!warning] You should only rarely consider backporting documentation to older stable releases. Legitimate reasons to backport documentation include legal issues, emergency security fixes, and fixes to content that might prevent users from upgrading or cause data loss.

To backport documentation changes in documentation releases older than the current stable branch:

1. Create an issue for the backport.
2. Create the merge request (MR) to backport the change.
3. Deploy the backport change.

Create an issue

Prerequisites:

• The person requesting the backport does this step. You must have at least the Developer role for the Technical Writing team tasks project.

1. Open an issue in the Technical Writing team tasks project using the backport changes template.

2. In the issue, state why the backport is needed. Include:

   • The background to this change.
   • Which specific documentation versions are changing.
   • How the documentation will change.
   • Links to any supporting issues or MRs.

3. Ask for the approval of technical writing leadership by creating a comment in this issue with the following text:

   plaintextCopy

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

After the technical writing leadership approves the backport, you can create the merge request to backport the change.

Create the merge request to backport the change

Prerequisites:

• The person requesting the backport does this step. You must have at least the Developer role on the project that needs the backport.

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

1. Open an MR with the backport by following the release docs guidelines, and mention the issue you opened before so that they are linked.

2. Assign the MR to a technical writer for review.

3. After the technical writer approves the MR, assign the MR to a release manager for review and merge.

   Mention this issue to the release manager, and provide them with all the context they need.

For the change to appear in:

• docs.gitlab.com, the release manager only has to merge the MR to the stable branch, and the technical writer needs to deploy the backport changes.
• gitlab.com/help, the change needs to be part of a GitLab release. The release manager can include the change in the next release they create. This step is optional.

Deploy the backport changes

Prerequisites:

• The technical writer assigned to the backport does this step. You must have at least the Maintainer role for the Technical Writing team tasks project.

After the changes are merged to the appropriate stable branch, you must deploy the backported changes.

Deploy changes made in GitLab 17.9 and later

Run a new pipeline in docs-gitlab-com. Choose the branch name that matches the stable version, for example 17.9.

• A parallel deployment for that branch is run and is deployed automatically.
• A Docker image is created that contains the versioned documentation and can be used offline.

Deploy changes made in GitLab 17.8 and earlier

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

• A Docker image is created that contains the versioned documentation and can be used offline.

Deploy changes made to a version other than the last three stable branches

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

1. Make sure the Docker images from the previous instructions are built.
2. Run a new pipeline in the gitlab-docs-archives repository.
3. After the pipeline finishes, go to https://archives.docs.gitlab.com and verify that the changes are available for the correct version.

View older documentation versions

Previous versions of the documentation are available on docs.gitlab.com. To view a previous version, in the upper-right corner, select the version number from the dropdown list.

To view versions that are not available on docs.gitlab.com:

• View the documentation archives.
• Go to the GitLab repository and select the version-specific branch. For example, the 13.2 branch has the documentation for GitLab 13.2.