Improve documentation release process docs

doc/development/documentation/site_architecture/release_process.md

@@ -4,191 +4,165 @@ group: unassigned
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
-# GitLab Docs monthly release process
+# Monthly release process
 
-When a new GitLab version is released on the 22nd, we need to create the respective
-single Docker image, and update some files so that the dropdown works correctly.
+When a new GitLab version is released on the 22nd, we need to release the published documentation
+for the new version.
 
-## 1. Add the chart version
+This should be done as soon as possible after the GitLab version is announced, so that:
 
-Since the charts use a different version number than all the other GitLab
-products, we need to add a
-[version mapping](https://docs.gitlab.com/charts/installation/version_mappings.html):
+- The published documentation includes the three most recent minor releases of the current major
+  version, and the most recent minor releases of the last two major versions. For example 13.9,
+  13.8, 13.7, 12.10, and 11.11.
+- Documentation updates after the 22nd are for the next release. The versions drop down
+  should have the current milestone with `-pre` appended to it, for example `13.10-pre`.
 
-The charts stable branch is not created automatically like the other products.
-There's an [issue to track this](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/1442).
-It is usually created on the 21st or the 22nd.
+Each documentation release:
 
-To add a new charts version:
+- Has a dedicated branch, named in the format `XX.yy`.
+- Has a Docker image that contains a build of that branch.
+
+For example:
+
+- For [GitLab 13.9](https://docs.gitlab.com/13.9/index.html), the
+  [stable branch](https://gitlab.com/gitlab-org/gitlab-docs/-/tree/13.9) and Docker image:
+  [`registry.gitlab.com/gitlab-org/gitlab-docs:13.9`](https://gitlab.com/gitlab-org/gitlab-docs/container_registry/631635).
+- For [GitLab 13.8](https://docs.gitlab.com/13.8/index.html), the
+  [stable branch](https://gitlab.com/gitlab-org/gitlab-docs/-/tree/13.8) and Docker image:
+  [`registry.gitlab.com/gitlab-org/gitlab-docs:13.8`](https://gitlab.com/gitlab-org/gitlab-docs/container_registry/631635).
+
+To set up a documentation release, follow these steps:
+
+1. [Add the charts version](#add-chart-version), so that the documentation is built using the
+   [version of the charts project that maps to](https://docs.gitlab.com/charts/installation/version_mappings.html)
+   the GitLab release. This step may have been completed already.
+1. [Create a stable branch and Docker image](#create-stable-branch-and-docker-image-for-release) for
+   the new version.
+1. [Create a release merge request](#create-release-merge-request) for the new version, which
+   updates the version dropdown menu for the current documentation and adds the release to the
+   Docker configuration. For example, the
+   [release merge request for 13.9](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/1555).
+1. [Update the three online versions](#update-dropdown-for-online-versions), so that they display the new release on their
+   version dropdown menus. For example:
+   - The merge request to [update the 13.9 version dropdown menu for the 13.9 release](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/1556).
+   - The merge request to [update the 13.8 version dropdown menu for the 13.9 release](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/1557).
+   - The merge request to [update the 13.7 version dropdown menu for the 13.9 release](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/1558).
+1. [Merge the release merge request and run the necessary Docker image builds](#merge-release-merge-request-and-run-docker-image-builds).
+
+## Add chart version
+
+To add a new charts version for the release:
 
 1. Make sure you're in the root path of the `gitlab-docs` repository.
 1. Open `content/_data/chart_versions.yaml` and add the new stable branch version using the
-   version mapping. Note that only the `major.minor` version is needed.
+   [version mapping](https://docs.gitlab.com/charts/installation/version_mappings.html). Only the
+   `major.minor` version is needed.
 1. Create a new merge request and merge it.
 
 NOTE:
-It can be handy to create the future mappings since they are pretty much known.
-In that case, when a new GitLab version is released, you don't have to repeat
-this first step.
+If you have time, add anticipated future mappings to `content/_data/chart_versions.yaml`. This saves
+a step for the next GitLab release.
 
-## 2. Create an image for a single version
+## Create stable branch and Docker image for release
 
-The single docs version must be created before the release merge request, but
-this needs to happen when the stable branches for all products have been created.
+To create a stable branch and Docker image for the release:
 
 1. Make sure you're in the root path of the `gitlab-docs` repository.
-1. Run the Rake task to create the single version:
+1. Run the Rake task to create the single version. For example, to create the 13.9 release branch
+   and perform others tasks:
 
    ```shell
-   ./bin/rake "release:single[12.0]"
+   ./bin/rake "release:single[13.9]"
    ```
 
-    A new `Dockerfile.12.0` should have been created and `.gitlab-ci.yml` should
-    have the branches variables updated into a new branch. They are automatically
-    committed.
+    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.
+
+1. 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>.
 
-1. 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 branch name you created in the first step. In the end, the
-   image is uploaded in the [Container Registry](https://gitlab.com/gitlab-org/gitlab-docs/container_registry)
-   and it is listed under the `registry` environment folder at
-   `https://gitlab.com/gitlab-org/gitlab-docs/-/environments/folders/registry` (must
-   have developer access).
+For example, see [the 13.9 release pipeline](https://gitlab.com/gitlab-org/gitlab-docs/-/pipelines/260288747).
 
-Optionally, you can test locally by building the image and running it:
+Optionally, you can test locally by:
 
-```shell
-docker build -t docs:12.0 -f Dockerfile.12.0 .
-docker run -it --rm -p 4000:4000 docs:12.0
-```
+1. Building the image and running it. For example, for GitLab 13.9 documentation:
 
-Visit `http://localhost:4000/12.0/` to see if everything works correctly.
+   ```shell
+   docker build -t docs:13.9 -f Dockerfile.13.9 .
+   docker run -it --rm -p 4000:4000 docs:13.9
+   ```
 
-## 3. Create the release merge request
+1. Visiting <http://localhost:4000/13.9/> to see if everything works correctly.
+
+## Create release merge request
 
 NOTE:
-To be [automated](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/750).
+An [epic is open](https://gitlab.com/groups/gitlab-org/-/epics/4361) to automate this step.
 
-Now it's time to create the monthly release merge request that adds the new
-version and rotates the old one:
+To create the release merge request for the release:
 
 1. Make sure you're in the root path of the `gitlab-docs` repository.
-1. Create a branch `release-X-Y`:
+1. Create a branch `release-X-Y`. For example:
 
    ```shell
    git checkout master
-   git checkout -b release-12-0
+   git checkout -b release-13-9
    ```
 
-1. **Rotate the online and offline versions:**
-
-   At any given time, there are 4 browsable online versions: one pulled from
-   the upstream master branches (docs for GitLab.com) and the three latest
-   stable versions.
+1. Edit `content/_data/versions.yaml` and update the lists of versions to reflect the new release:
 
-   Edit `content/_data/versions.yaml` and rotate the versions to reflect the
-   new changes:
+   - 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:`.
 
-   - `online`: The 3 latest stable versions.
-   - `offline`: All the previous versions offered as an offline archive.
+1. Update these Dockerfiles:
 
-1. **Update the `:latest` and `:archives` Docker images:**
+   - `dockerfiles/Dockerfile.archives`: Add the latest version to the top of the list.
+   - `Dockerfile.master`: Remove the oldest version, and add the newest version to the
+     top of the list.
 
-   The following two Dockerfiles need to be updated:
-
-   1. `dockerfiles/Dockerfile.archives` - Add the latest version at the top of
-      the list.
-   1. `Dockerfile.master` - Rotate the versions (oldest gets removed and latest
-       is added at the top of the list).
-
-1. In the end, there should be four files in total that have changed.
-   Commit and push to create the merge request using the "Release" template:
+1. Commit and push to create the merge request. For example:
 
    ```shell
    git add content/ Dockerfile.master dockerfiles/Dockerfile.archives
-   git commit -m "Release 12.0"
-   git push origin release-12-0
+   git commit -m "Release 13.9"
+   git push origin release-13-9
    ```
 
-## 4. Update the dropdown for all online versions
-
-The versions dropdown is in a way "hardcoded". When the site is built, it looks
-at the contents of `content/_data/versions.yaml` and based on that, the dropdown
-is populated. Older branches have different content, which means the
-dropdown list is one or more releases behind. Remember that the new changes of
-the dropdown are included in the unmerged `release-X-Y` branch.
+Do not merge the release merge request yet.
 
-The content of `content/_data/versions.yaml` needs to change for all online
-versions (stable branches `X.Y` of the `gitlab-docs` project):
+## Update dropdown for online versions
 
-1. Run the Rake task that creates all the respective merge requests needed to
-   update the dropdowns. Set these to automatically be merged when their
-   pipelines succeed:
+To update`content/_data/versions.yaml` for all online versions (stable branches `X.Y` of the
+`gitlab-docs` project):
 
-   NOTE:
-   The `release-X-Y` branch needs to be present locally,
-   and you need to have switched to it, otherwise the Rake task fails.
+1. Run the Rake task that creates all of the necessary merge requests to update the dropdowns. For
+   example, for the 13.9 release:
 
    ```shell
-   git checkout release-X-Y
+   git checkout release-13-9
    ./bin/rake release:dropdowns
    ```
 
-1. [Visit the merge requests page](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests?label_name%5B%5D=release)
-   to check that their pipelines pass, and once all are merged, proceed to the
-   following and final step.
+   These merge requests are set to automatically merge.
 
-NOTE:
-In case a pipeline fails, see [troubleshooting](#troubleshooting).
+1. [Visit the merge requests page](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests?label_name%5B%5D=release)
+   to check that their pipelines pass. After all MRs are merged, proceed to the following and final
+   step.
 
-## 5. Merge the release merge request
+## Merge release merge request and run Docker image builds
 
-The dropdown merge requests should have now been merged into their respective
-version (stable `X.Y` branch), which triggers another pipeline. At this point,
-you need to only babysit the pipelines and make sure they don't fail:
+The merge requests for the dropdowns should now all be merged into their respective stable branches.
+Each merge triggers a new pipeline for each stable branch. Wait for the stable branch pipelines to
+complete, then:
 
 1. Check the [pipelines page](https://gitlab.com/gitlab-org/gitlab-docs/pipelines)
    and make sure all stable branches have green pipelines.
-1. After all the pipelines of the online versions succeed, merge the release merge request.
+1. After all the pipelines succeed, merge the [release merge request](#create-release-merge-request).
 1. Finally, run the
    [`Build docker images weekly` pipeline](https://gitlab.com/gitlab-org/gitlab-docs/pipeline_schedules)
    that builds the `:latest` and `:archives` Docker images.
 
-Once the scheduled pipeline succeeds, the docs site is deployed with all
-new versions online.
-
-## Troubleshooting
-
-Releasing a new version is a long process that involves many moving parts.
-
-### `test_internal_links_and_anchors` failing on dropdown merge requests
-
-WARNING:
-We now pin versions in the `.gitlab-ci.yml` of the respective branch,
-so the steps below are deprecated.
-
-When [updating the dropdown for the stable versions](#4-update-the-dropdown-for-all-online-versions),
-there may be cases where some links might fail. The process of how the
-dropdown MRs are created have a caveat, and that is that the tests run by
-pulling the master branches of all products, instead of the respective stable
-ones.
-
-In a real world scenario, the [Update 12.2 dropdown to match that of 12.4](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/604)
-merge request failed because of the [`test_internal_links_and_anchors` test](https://gitlab.com/gitlab-org/gitlab-docs/-/jobs/328042431).
-
-This happened because there has been a rename of a product (`gitlab-monitor` to `gitlab-exporter`)
-and the old name was still referenced in the 12.2 docs. If the respective stable
-branches for 12.2 were used, this wouldn't have failed, but as we can see from
-the [`compile_dev` job](https://gitlab.com/gitlab-org/gitlab-docs/-/jobs/328042427),
-the `master` branches were pulled.
-
-To fix this, re-run the pipeline (`https://gitlab.com/gitlab-org/gitlab-docs/pipelines/new`)
-for the `update-12-2-for-release-12-4` branch, by including the following CI/CD variables:
-
-- `BRANCH_CE` set to `12-2-stable`
-- `BRANCH_EE` set to `12-2-stable-ee`
-- `BRANCH_OMNIBUS` set to `12-2-stable`
-- `BRANCH_RUNNER` set to `12-2-stable`
-- `BRANCH_CHARTS` set to `2-2-stable`
-
-This should make the MR pass.
+As the last step in the scheduled pipeline, the documentation site deploys with all new versions.