Add latest changes from gitlab-org/gitlab@13-10-stable-eev13.10.0-rc41

6 files changed, 131 insertions, 158 deletions

diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md
index c9c291abd2c..8fe3f0cbf8e 100644
--- a/doc/development/documentation/feature_flags.md
+++ b/doc/development/documentation/feature_flags.md
@@ -14,9 +14,13 @@ feature flag depends on its state (enabled or disabled). When the state
 changes, the developer who made the change **must update the documentation**
 accordingly.
 
+Every feature introduced to the codebase, even if it's behind a feature flag,
+must be documented. For context, see the
+[latest merge request that updated this guideline](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47917#note_459984428).
+
 ## Criteria
 
-According to the process of [deploying GitLab features behind feature flags](../feature_flags/process.md):
+According to the process of [deploying GitLab features behind feature flags](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle):
 
 > - _By default, feature flags should be off._
 > - _Feature flags should remain in the codebase for a short period as possible to reduce the need for feature flag accounting._
diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md
index 92fd17f9d3e..70fa80b3306 100644
--- a/doc/development/documentation/site_architecture/index.md
+++ b/doc/development/documentation/site_architecture/index.md
@@ -118,7 +118,7 @@ If you change the Dockerfile configuration and rebuild the images, you can break
 pipeline in the main `gitlab` repository as well as in `gitlab-docs`. Create an image with
 a different name first and test it to ensure you do not break the pipelines.
 
-1. In [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs), go to **{rocket}** **CI / CD > Pipelines**.
+1. In [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs), go to **{rocket}** **CI/CD > Pipelines**.
 1. Click the **Run Pipeline** button.
 1. See that a new pipeline is running. The jobs that build the images are in the first
    stage, `build-images`. You can click the pipeline number to see the larger pipeline
@@ -137,7 +137,7 @@ and deploys it to <https://docs.gitlab.com>.
 
 If you need to build and deploy the site immediately (must have maintainer level permissions):
 
-1. In [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs), go to **{rocket}** **CI / CD > Schedules**.
+1. In [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs), go to **{rocket}** **CI/CD > Schedules**.
 1. For the `Build docs.gitlab.com every 4 hours` scheduled pipeline, click the **play** (**{play}**) button.
 
 Read more about the [deployment process](deployment_process.md).
diff --git a/doc/development/documentation/site_architecture/release_process.md b/doc/development/documentation/site_architecture/release_process.md
index ba5363dbb71..7bdf3fbdcf8 100644
--- a/doc/development/documentation/site_architecture/release_process.md
+++ b/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 environment 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.
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
deleted file mode 100644
index ade0b89a92c..00000000000
--- a/doc/development/documentation/styleguide.md
+++ /dev/null
@@ -1,8 +0,0 @@
----
-redirect_to: 'styleguide/index.md'
----
-
-This document was moved to [another location](styleguide/index.md).
-
-<!-- This redirect file can be deleted after <2022-02-13>. -->
-<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md
index 7737aa58506..4831e5bbce5 100644
--- a/doc/development/documentation/styleguide/index.md
+++ b/doc/development/documentation/styleguide/index.md
@@ -108,7 +108,7 @@ of GitLab more efficient.
 
 New information that would be useful toward the future usage or troubleshooting
 of GitLab should not be written directly in a forum or other messaging system,
-but added to a documentation MR and then referenced, as described above. 
+but added to a documentation MR and then referenced, as described above.
 
 The more we reflexively add information to the documentation, the more
 the documentation helps others efficiently accomplish tasks and solve problems.
@@ -601,6 +601,7 @@ Follow these guidelines for punctuation:
 
 | Rule                                                             | Example                                                |
 |------------------------------------------------------------------|--------------------------------------------------------|
+| Avoid semicolons. Use two sentences instead.                     | _That's the way that the world goes 'round. You're up one day and the next you're down._
 | Always end full sentences with a period.                         | _For a complete overview, read through this document._ |
 | Always add a space after a period when beginning a new sentence. | _For a complete overview, check this doc. For other references, check out this guide._ |
 | Do not use double spaces. (Tested in [`SentenceSpacing.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SentenceSpacing.yml).) | --- |
@@ -1606,34 +1607,32 @@ displayed for the page or feature.
 
 #### Version text in the **Version History**
 
-If all content in a section is related, add version text after the header
-for the section. The version information must be surrounded by blank lines, and
-each entry should be on its own line.
+If all content in a section is related, add version text after the header for
+the section. The version information must:
 
-Add the version history information as a blockquote:
+- Be surrounded by blank lines.
+- Start with `>`. If there are multiple bullets, each line must start with `> -`.
+- The string must include these words in this order (capitalization doesn't matter):
+  - `introduced`, `deprecated`, `moved`
+  - `in` or `to`
+  - `GitLab`
+- Whenever possible, include a link to the completed issue, merge request, or epic
+  that introduced the feature. An issue is preferred over a merge request, and
+  a merge request is preferred over an epic.
 
 ```markdown
 ## Feature name
 
-> Introduced in GitLab 11.3.
+> [Introduced](<link-to-issue>) in GitLab 11.3.
 
 This feature does something.
-```
 
-Whenever possible, version text should have a link to the completed issue, merge
-request, or epic that introduced the feature. An issue is preferred over a merge
-request, and a merge request is preferred over an epic. For example:
+## Feature name 2
 
-```markdown
-> [Introduced](<link-to-issue>) in GitLab 11.3.
-```
-
-If you're adding information about new features or changes in a release, update
-the blockquote to use a bulleted list:
-
-```markdown
 > - [Introduced](<link-to-issue>) in GitLab 11.3.
-> - Enabled by default in GitLab 11.4.
+> - [Enabled by default](<link-to-issue>) in GitLab 11.4.
+
+This feature does something else.
 ```
 
 If a feature is moved to another tier:
diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md
index f3d6e0a5c71..eed544911cb 100644
--- a/doc/development/documentation/testing.md
+++ b/doc/development/documentation/testing.md
@@ -272,7 +272,11 @@ To configure Vale in your editor, install one of the following as appropriate:
   In the extension's settings:
 
   - Select the **Use CLI** checkbox.
-  - In the **Config** setting, enter an absolute path to [`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/blob/master/.vale.ini) in one of the cloned GitLab repositories on your computer.
+  - In the <!-- vale gitlab.Spelling = NO --> **Config** setting, enter an absolute
+    path to [`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/blob/master/.vale.ini)
+    in one of the cloned GitLab repositories on your computer.
+    <!-- vale gitlab.Spelling = YES -->
+
   - In the **Path** setting, enter the absolute path to the Vale binary. In most
     cases, `vale` should work. To find the location, run `which vale` in a terminal.