Add latest changes from gitlab-org/gitlab@master

10 files changed, 60 insertions, 30 deletions

diff --git a/doc/development/auto_devops.md b/doc/development/auto_devops.md
index d11587a864d..c127858d3e7 100644
--- a/doc/development/auto_devops.md
+++ b/doc/development/auto_devops.md
@@ -53,6 +53,6 @@ issue for discussion around setting up Auto DevOps development environments.
 ## Monitoring on GitLab.com
 
 The metric
-[`auto_devops_completed_pipelines_total`](https://thanos-query.ops.gitlab.net/graph?g0.range_input=72h&g0.max_source_resolution=0s&g0.expr=sum(increase(auto_devops_pipelines_completed_total%7Benvironment%3D%22gprd%22%7D%5B60m%5D))%20by%20(status)&g0.tab=0)
+[`auto_devops_completed_pipelines_total`](https://thanos.gitlab.net/graph?g0.range_input=72h&g0.max_source_resolution=0s&g0.expr=sum(increase(auto_devops_pipelines_completed_total%7Benvironment%3D%22gprd%22%7D%5B60m%5D))%20by%20(status)&g0.tab=0)
 (only available to GitLab team members) counts completed Auto DevOps
 pipelines, labeled by status.
diff --git a/doc/development/database/client_side_connection_pool.md b/doc/development/database/client_side_connection_pool.md
index 1a30d2d73a3..8316a75ac8d 100644
--- a/doc/development/database/client_side_connection_pool.md
+++ b/doc/development/database/client_side_connection_pool.md
@@ -43,7 +43,7 @@ hardcoded value (10).
 At this point, we need to investigate what is using more connections
 than we anticipated. To do that, we can use the
 `gitlab_ruby_threads_running_threads` metric. For example, [this
-graph](https://thanos-query.ops.gitlab.net/graph?g0.range_input=1h&g0.max_source_resolution=0s&g0.expr=sum%20by%20(thread_name)%20(%20gitlab_ruby_threads_running_threads%7Buses_db_connection%3D%22yes%22%7D%20)&g0.tab=0)
+graph](https://thanos.gitlab.net/graph?g0.range_input=1h&g0.max_source_resolution=0s&g0.expr=sum%20by%20(thread_name)%20(%20gitlab_ruby_threads_running_threads%7Buses_db_connection%3D%22yes%22%7D%20)&g0.tab=0)
 shows all running threads that connect to the database by their
 name. Threads labeled `puma worker` or `sidekiq_worker_thread` are
 the threads that define `Gitlab::Runtime.max_threads` so those are
diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md
index c9c291abd2c..d318390b210 100644
--- a/doc/development/documentation/feature_flags.md
+++ b/doc/development/documentation/feature_flags.md
@@ -14,6 +14,10 @@ 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):
diff --git a/doc/development/experiment_guide/index.md b/doc/development/experiment_guide/index.md
index 21c61324dc1..4e1fa65108e 100644
--- a/doc/development/experiment_guide/index.md
+++ b/doc/development/experiment_guide/index.md
@@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 Experiments can be conducted by any GitLab team, most often the teams from the [Growth Sub-department](https://about.gitlab.com/handbook/engineering/development/growth/). Experiments are not tied to releases because they primarily target GitLab.com.
 
-Experiments are run as an A/B test and are behind a feature flag to turn the test on or off. Based on the data the experiment generates, the team decides if the experiment had a positive impact and should be made the new default or rolled back.
+Experiments are run as an A/B/n test, and are behind a feature flag to turn the test on or off. Based on the data the experiment generates, the team decides if the experiment had a positive impact and should be made the new default, or rolled back.
 
 ## Experiment tracking issue
 
@@ -36,21 +36,39 @@ and link to the issue that resolves the experiment. If the experiment is
 successful and becomes part of the product, any follow up issues should be
 addressed.
 
-## Experiments using `gitlab-experiment`
+## Implement an experiment
+
+There are two options to conduct experiments:
+
+1. [GitLab Experiment](https://gitlab.com/gitlab-org/gitlab-experiment/) is a gem included in GitLab.
+1. [`Experimentation Module`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib%2Fgitlab%2Fexperimentation.rb) is built in the GitLab codebase.
+
+Both methods use [experiment](../feature_flags/development.md#experiment-type) feature flags.
+
+Historical Context: `Experimentation Module` was built iteratively with the needs that appeared while implementing Growth sub-department experiments. The `gitlab-experiment` gem was built with the learnings of the `Experimentation Module` and an easier to use API.
+
+Currently both methods for running experiments are included in the codebase. The features are slightly different:
+
+| Feature | `Experiment Module` | `gitlab-experiment` |
+| ------ | ------ | ------ |
+| Record user grouping | Yes | No (not natively) |
+| Uses feature flags | Yes | Yes |
+| Multivariate | No | Yes |
+
+However, there is currently no strong suggestion to use one over the other.
+
+### Experiments using `gitlab-experiment` **(FREE SAAS)**
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300383) in GitLab 13.7.
 > - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default.
 > - It's enabled on GitLab.com.
 > - It is not yet intended for use in GitLab self-managed instances.
 
-[GitLab Experiment](https://gitlab.com/gitlab-org/gitlab-experiment/) is a gem included
-in GitLab that can be used for running experiments.
-
-## How to create an A/B test using `experimentation.rb`
+You find out how to conduct experiments using `gitlab-experiment` in the [README](https://gitlab.com/gitlab-org/gitlab-experiment/-/blob/master/README.md).
 
-### Implement the experiment
+### Experiments using the `Experimentation Module`
 
-1. Add the experiment to the `Gitlab::Experimentation::EXPERIMENTS` hash in [`experimentation.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib%2Fgitlab%2Fexperimentation.rb):
+1. Add the experiment to the `Gitlab::Experimentation::EXPERIMENTS` hash in the [`Experimentation Module`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib%2Fgitlab%2Fexperimentation.rb):
 
    ```ruby
    EXPERIMENTS = {
@@ -151,13 +169,13 @@ in GitLab that can be used for running experiments.
      end
      ```
 
-### Implement the tracking events
+#### Implement the tracking events
 
 To determine whether the experiment is a success or not, we must implement tracking events
 to acquire data for analyzing. We can send events to Snowplow via either the backend or frontend.
 Read the [product intelligence guide](https://about.gitlab.com/handbook/product/product-intelligence-guide/) for more details.
 
-#### Track backend events
+##### Track backend events
 
 The framework provides the following helper method that is available in controllers:
 
@@ -190,7 +208,7 @@ context 'when the experiment is active and the user is in the experimental group
 end
 ```
 
-#### Track frontend events
+##### Track frontend events
 
 The framework provides the following helper method that is available in controllers:
 
@@ -273,7 +291,7 @@ describe('event tracking', () => {
 });
 ```
 
-### Record experiment user
+#### Record experiment user
 
 In addition to the anonymous tracking of events, we can also record which users have participated in which experiments and whether they were given the control experience or the experimental experience.
 
@@ -289,7 +307,7 @@ Subsequent calls to this method for the same experiment and the same user have n
 
 Note that this data is completely separate from the [events tracking data](#implement-the-tracking-events). They are not linked together in any way.
 
-#### Add context
+##### Add context
 
 You can add arbitrary context data in a hash which gets stored as part of the experiment user record. New calls to the `record_experiment_user` with newer contexts get merged deeply into the existing context.
 
@@ -306,7 +324,7 @@ record_experiment_user(:signup_flow, foo: 40, bar: { b: 2 }, thor: 3)
 # context becomes { "foo" => 40, "bar" => { "a" => 22, "b" => 2 }, "thor" => 3}
 ```
 
-### Record experiment conversion event
+#### Record experiment conversion event
 
 Along with the tracking of backend and frontend events and the [recording of experiment participants](#record-experiment-user), we can also record when a user performs the desired conversion event action. For example:
 
@@ -323,7 +341,7 @@ end
 
 Note that the use of this method requires that we have first [recorded the user as being part of the experiment](#record-experiment-user).
 
-### Enable the experiment
+#### Enable the experiment
 
 After all merge requests have been merged, use [`chatops`](../../ci/chatops/index.md) in the
 [appropriate channel](../feature_flags/controls.md#communicate-the-change) to start the experiment for 10% of the users.
@@ -340,7 +358,7 @@ For visibility, please also share any commands run against production in the `#s
   /chatops run feature delete signup_flow_experiment_percentage
   ```
 
-### Manually force the current user to be in the experiment group
+#### Manually force the current user to be in the experiment group
 
 You may force the application to put your current user in the experiment group. To do so
 add a query string parameter to the path where the experiment runs. If you do so,
@@ -353,7 +371,7 @@ to the URL:
 https://gitlab.com/<EXPERIMENT_ENTRY_URL>?force_experiment=<EXPERIMENT_KEY>
 ```
 
-### A cookie-based approach to force an experiment
+#### A cookie-based approach to force an experiment
 
 It's possible to force the current user to be in the experiment group for `<EXPERIMENT_KEY>`
 during the browser session by using your browser's developer tools:
@@ -374,9 +392,9 @@ To clear the experiments, unset the `force_experiment` cookie:
 document.cookie = "force_experiment=; path=/";
 ```
 
-### Testing and test helpers
+#### Testing and test helpers
 
-#### RSpec
+##### RSpec
 
 Use the following in RSpec to mock the experiment:
 
@@ -404,7 +422,7 @@ context 'when the experiment is active' do
 end
 ```
 
-#### Jest
+##### Jest
 
 Use the following in Jest to mock the experiment:
 
diff --git a/doc/development/fe_guide/accessibility.md b/doc/development/fe_guide/accessibility.md
index 977c2c456f9..5f22c13ca06 100644
--- a/doc/development/fe_guide/accessibility.md
+++ b/doc/development/fe_guide/accessibility.md
@@ -161,7 +161,7 @@ unnecessary when using `gl-icon`.
 // good - decorative images hidden from screen readers
 <img src="decorative.jpg" alt="">
 <svg role="img" alt="">
-<gl-icon name="epic"/> 
+<gl-icon name="epic"/>
 ```
 
 ## When should ARIA be used
@@ -187,7 +187,7 @@ Use of ARIA would then only occur in [GitLab UI](https://gitlab.com/gitlab-org/g
 We have two options for Web accessibility testing:
 
 - [axe](https://www.deque.com/axe/) for [Firefox](https://addons.mozilla.org/en-US/firefox/addon/axe-devtools/)
-- [axe](https://www.deque.com/axe/) for [Chrome](https://chrome.google.com/webstore/detail/axe-web-accessibility-tes/lhdoppojpmngadmnindnejefpokejbdd)
+- [axe](https://www.deque.com/axe/) for [Chrome](https://chrome.google.com/webstore/detail/axe-devtools-web-accessib/lhdoppojpmngadmnindnejefpokejbdd)
 
 ### Other links
 
diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md
index a6d9ba861b0..745ec50bdcd 100644
--- a/doc/development/go_guide/index.md
+++ b/doc/development/go_guide/index.md
@@ -91,7 +91,7 @@ projects:
 - Avoid global variables, even in packages. By doing so you introduce side
   effects if the package is included multiple times.
 - Use `goimports` before committing.
-  [`goimports`](https://godoc.org/golang.org/x/tools/cmd/goimports)
+  [`goimports`](https://pkg.go.dev/golang.org/x/tools/cmd/goimports)
   is a tool that automatically formats Go source code using
   [`Gofmt`](https://golang.org/cmd/gofmt/), in addition to formatting import lines,
   adding missing ones and removing unreferenced ones.
diff --git a/doc/development/i18n/translation.md b/doc/development/i18n/translation.md
index 25dc854d2a3..7fb49521106 100644
--- a/doc/development/i18n/translation.md
+++ b/doc/development/i18n/translation.md
@@ -22,9 +22,17 @@ You may create a new account or use any of their supported sign in services.
 
 GitLab is being translated into many languages.
 
-1. Select the language you would like to contribute translations to by clicking the flag
+1. Find the language that you want to contribute to, in our
+   [GitLab Crowdin project](https://crowdin.com/project/gitlab-ee).
+   - If the language that you're looking for is available, proceed
+     to the next step.
+   - If the language you are looking for is not available,
+      [open an issue](https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&utf8=✓&state=all&label_name[]=Category%3AInternationalization). Notify our Crowdin
+      administrators by including `@gitlab-org/manage/import` in your issue.
+      in the issue.
+   - After the issue/Merge Request is complete, restart this procedure.
 1. Next, you can view list of files and folders.
-  Click `gitlab.pot` to open the translation editor.
+   Select `gitlab.pot` to open the translation editor.
 
 ### Translation Editor
 
diff --git a/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md b/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md
index b6293ec41b8..ea48a3aa8b8 100644
--- a/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md
+++ b/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md
@@ -151,7 +151,7 @@ To run the Monitor tests locally, against the GDK, please follow the preparation
 1. The test setup deploys the app in a Kubernetes cluster, using the Auto DevOps deployment strategy.
 To enable Auto DevOps in GDK, follow the [associated setup](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/auto_devops/index.md#setup) instructions. If you have problems, review the [troubleshooting guide](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/auto_devops/tips_and_troubleshooting.md) or reach out to the `#gdk` channel in the internal GitLab Slack.
 1. Do [secure your GitLab instance](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/auto_devops/index.md#secure-your-gitlab-instance) since it is now publicly accessible on `https://[YOUR-PORT].qa-tunnel.gitlab.info`.
-1. Install the Kubernetes command line tool known as `kubectl`. Use the [official installation instructions](https://kubernetes.io/docs/tasks/tools/install-kubectl/).
+1. Install the Kubernetes command line tool known as `kubectl`. Use the [official installation instructions](https://kubernetes.io/docs/tasks/tools/).
 
 You might see NGINX issues when you run `gdk start` or `gdk restart`. In that case, run `sft login` to revalidate your credentials and regain access the QA Tunnel.
 
diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md
index 059983f790e..9facca10142 100644
--- a/doc/development/testing_guide/frontend_testing.md
+++ b/doc/development/testing_guide/frontend_testing.md
@@ -212,7 +212,7 @@ When it comes to querying DOM elements in your tests, it is best to uniquely and
 the element.
 
 Preferentially, this is done by targeting what the user actually sees using [DOM Testing Library](https://testing-library.com/docs/dom-testing-library/intro/).
-When selecting by text it is best to use [`getByRole` or `findByRole`](https://testing-library.com/docs/queries/byrole)
+When selecting by text it is best to use [`getByRole` or `findByRole`](https://testing-library.com/docs/queries/byrole/)
 as these enforce accessibility best practices as well. The examples below demonstrate the order of preference.
 
 When writing Vue component unit tests, it can be wise to query children by component, so that the unit test can focus on comprehensive value coverage
diff --git a/doc/development/testing_guide/review_apps.md b/doc/development/testing_guide/review_apps.md
index dcaa2680a8b..c4194be23a4 100644
--- a/doc/development/testing_guide/review_apps.md
+++ b/doc/development/testing_guide/review_apps.md
@@ -112,7 +112,7 @@ Review Apps are automatically stopped 2 days after the last deployment thanks to
 the [Environment auto-stop](../../ci/environments/index.md#stop-an-environment-after-a-certain-time-period) feature.
 
 If you need your Review App to stay up for a longer time, you can
-[pin its environment](../../ci/environments/index.md#auto-stop-example) or retry the
+[pin its environment](../../ci/environments/index.md#override-a-deployments-scheduled-stop-time) or retry the
 `review-deploy` job to update the "latest deployed at" time.
 
 The `review-cleanup` job that automatically runs in scheduled