Skip to content

Release 14.6

Fiona Neill requested to merge release-14-6 into main

Follow the process in Monthly documentation releases.

Recommended timeline

To minimize problems during the documentation release process, use the following timeline:

Create stable branch and Docker image for release

To create a stable branch of the gitlab-docs project and a Docker image for the release:

  1. Make sure you're in the root path of the gitlab-docs repository.

  2. Run the Rake task to create the single version. For example, to create the 13.9 release branch and perform other tasks:

    ./bin/rake "release:single[13.9]"

    A branch for the release is created, a new Dockerfile.13.9 is created, and .gitlab-ci.yml has branches variables updated into a new branch. These files are automatically committed.

  3. Push the newly created branch, but don't create a merge request. After you push, the image:docs-single job creates a new Docker image tagged with the name of the branch you created earlier. You can see the Docker image in the registry environment at https://gitlab.com/gitlab-org/gitlab-docs/-/environments/folders/registry.

For example, see the 13.9 release pipeline.

If the pipeline fails, the new Docker image is not created and so not added to the registry.

Optional. Test locally

Prerequisite:

  • Install Docker. To verify, run which docker.

  1. Build the image and run it. For example, for GitLab 13.9 documentation:

    docker build -t docs:13.9 -f Dockerfile.13.9 .
docker run -it --rm -p 4000:4000 docs:13.9

    If you get a permission error, try running the commands prefixed with sudo.

    If you're informed that the Docker daemon isn't running, start it manually:

  2. Visit http://localhost:4000/13.9 to see if everything works correctly.

  3. Stop the Docker container:

    1. Identify the container's ID with docker container ls.
    2. Run docker stop <container ID>.

Create release merge request

Note: An epic is open to automate this step.

To create the release merge request for the release:

  1. Make sure you're in the root path of the gitlab-docs repository.

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

    git checkout main
git checkout -b release-13-9

  3. Edit content/_data/versions.yaml and update the lists of versions to reflect the new release:

    • Add the latest version to the online: section.
    • Move the oldest version in online: to the offline: section. There should now be three versions in online:.

  4. Edit Dockerfile.main by removing the oldest version, and then adding the newest version to the top of the list.

  5. Commit and push to create the merge request. For example:

    git add content/_data/versions.yaml Dockerfile.main
git commit -m "Release 13.9"
git push origin release-13-9

  6. Create the merge request and choose the Release description template. Set the merge request to Draft status and do not merge it yet.

Update dropdown for online versions

To update content/_data/versions.yaml for all online versions (stable branches X.Y of the gitlab-docs project).

Update dropdowns for the current major version

  1. Run the Rake task that creates the merge requests to update the dropdowns for the current major version. For example, for the 14.4 release:

    git checkout release-14-4
./bin/rake release:dropdowns

    For the 14.4 release, the task created the following three merge requests:

  2. Visit the merge requests page to check that their pipelines pass. Set each merge request to draft status and do not merge them yet.

Update dropdowns for the previous major versions

The previous major versions are listed under the current versions in the docs:

Previous major dropdowns

The process to update the dropdowns for the previous major versions is not automated, so you must create the merge requests manually. For simplicity, these steps assume you are updating the 13.12 and 12.10 dropdowns. The steps should be updated when we move to the next major release (15.0).

  1. Create a branch off the stable branch for 13.12. Use update-13.12-for-release-<new-version> for the branch name. For example:

    git checkout -b update-13.12-for-release-14.4 origin/13.12

  2. Edit content/_data/versions.yaml and update the list of versions to reflect the new release:

    • Add the latest version to the online: section.
    • Remove the oldest version in online:. There should now be three versions in online:.

  3. Commit and push. For example, for the 14.4 release:

    git add content/_data/versions.yaml
git commit -m "Update dropdown to 14.4"
git push origin update-13.12-for-release-14.4

  4. Create the merge request:

    • For the target branch, select the previous version's stable branch, in this case, 13.12 (do not select main!)
    • Add the ~Technical Writing and ~release labels.
    • Set the merge request to draft status.
    • Example merge request for the 14.4 release.

  5. Create a branch off the stable branch for 12.10. Use update-12.10-for-release-<new-version> for the branch name. For example:

    git checkout -b update-12.10-for-release-14.4 origin/12.10

  6. Edit content/_data/versions.yaml and update the list of versions to reflect the new release:

    • Add the latest version to the online: section.
    • Remove the oldest current version from online:.

  7. Commit and push. For example, for the 14.4 release:

    git add content/_data/versions.yaml
git commit -m "Update dropdown to 14.4"
git push origin update-12.10-for-release-14.4

  8. Create the merge request:

    • For the target branch, select the previous version's stable branch, in this case, 12.10 (do not select main!)
    • Add the ~Technical Writing and ~release labels.
    • Set the merge request to draft status.
    • Example merge request for the 14.4 release.

  9. Visit the merge requests page to check that their pipelines pass. Do not merge them yet.

Merge merge requests and run Docker image builds

Do this after the release post is live.

The merge requests for the dropdowns should now all be merged into their respective stable branches.

  1. Check the pipelines page and make sure all stable branches have green pipelines.
  2. Merge all of the dropdown merge requests.
  3. Merge the release merge request.
  4. Each merge triggers a new pipeline for each stable branch. Check the pipelines page and wait for all the stable branch pipelines to complete.
  5. Go to the scheduled pipelines page and run the Build docker images weekly pipeline that builds the :latest Docker image.
  6. In the scheduled pipeline you just started, manually run the image:docs-latest job.
  7. When the pipeline is complete, run the Build docs.gitlab.com every 4 hours scheduled pipeline to deploy all new versions to the public documentation site. You don't need to run any jobs manually for this second pipeline.

Post-deployment checklist

After the documentation is released, verify the documentation site has been deployed as expected. Open site docs.gitlab.com in a browser and confirm both the latest version and the correct pre- version are listed in the documentation version dropdown.

For example, if you released the 14.1 documentation, the first dropdown entry should be GitLab.com (14.2-pre), followed by 14.1.

Edited by Fiona Neill

Merge request reports