Add latest changes from gitlab-org/gitlab@14-0-stable-eev14.0.0-rc42

3 files changed, 41 insertions, 10 deletions

diff --git a/doc/development/experiment_guide/experimentation.md b/doc/development/experiment_guide/experimentation.md
index 7135f8acd9b..ee0f63342f1 100644
--- a/doc/development/experiment_guide/experimentation.md
+++ b/doc/development/experiment_guide/experimentation.md
@@ -6,10 +6,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Create an A/B test with `Experimentation Module`
 
+NOTE:
+We recommend using [GLEX](gitlab_experiment.md) for new experiments.
+
 ## Implement the experiment
 
 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):
+   [`experimentation.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib%2Fgitlab%2Fexperimentation.rb):
 
    ```ruby
    EXPERIMENTS = {
diff --git a/doc/development/experiment_guide/gitlab_experiment.md b/doc/development/experiment_guide/gitlab_experiment.md
index db9bc521cfd..820d1da0080 100644
--- a/doc/development/experiment_guide/gitlab_experiment.md
+++ b/doc/development/experiment_guide/gitlab_experiment.md
@@ -394,6 +394,26 @@ You may be asked from time to time to track a specific record ID in experiments.
 The approach is largely up to the PM and engineer creating the implementation.
 No recommendations are provided here at this time.
 
+### Record experiment subjects
+
+Snowplow tracking of identifiable users or groups is prohibited, but you can still
+determine if an experiment is successful or not. We're allowed to record the ID of
+a namespace, project or user in our database. Therefore, we can tell the experiment
+to record their ID together with the assigned experiment variant in the
+`experiment_subjects` database table for later analysis.
+
+For the recording to work, the experiment's context must include a `namespace`,
+`group`, `project`, `user`, or `actor`.
+
+To record the experiment subject when you first assign a variant, call `record!` in
+the experiment's block:
+
+```ruby
+experiment(:pill_color, actor: current_user) do |e|
+  e.record!
+end
+```
+
 ## Test with RSpec
 
 This gem provides some RSpec helpers and custom matchers. These are in flux as of GitLab 13.10.
diff --git a/doc/development/experiment_guide/index.md b/doc/development/experiment_guide/index.md
index 0d534a974a1..798c6ff84d0 100644
--- a/doc/development/experiment_guide/index.md
+++ b/doc/development/experiment_guide/index.md
@@ -12,7 +12,7 @@ Experiments are run as an A/B/n test, and are behind a feature flag to turn the
 
 ## Experiment tracking issue
 
-Each experiment should have an [Experiment tracking](https://gitlab.com/groups/gitlab-org/-/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=growth%20experiment&search=%22Experiment+tracking%22) issue to track the experiment from roll-out through to cleanup/removal. The tracking issue is similar to a feature flag rollout issue, and is also used to track the status of an experiment. Immediately after an experiment is deployed, the due date of the issue should be set (this depends on the experiment but can be up to a few weeks in the future).
+Each experiment should have an [Experiment tracking](https://gitlab.com/groups/gitlab-org/-/issues?scope=all&state=opened&label_name[]=growth%20experiment&search=%22Experiment+tracking%22) issue to track the experiment from roll-out through to cleanup/removal. The tracking issue is similar to a feature flag rollout issue, and is also used to track the status of an experiment. Immediately after an experiment is deployed, the due date of the issue should be set (this depends on the experiment but can be up to a few weeks in the future).
 After the deadline, the issue needs to be resolved and either:
 
 - It was successful and the experiment becomes the new default.
@@ -46,17 +46,25 @@ One is built into GitLab directly and has been around for a while (this is calle
 to as `Gitlab::Experiment` -- GLEX for short.
 
 Both approaches use [experiment](../feature_flags/index.md#experiment-type)
-feature flags, and there is currently no strong suggestion to use one over the other.
+feature flags. We recommend using GLEX rather than `Experimentation Module` for new experiments.
 
-| Feature              | `Experimentation Module` | GLEX |
-| -------------------- |------------------------- | ---- |
-| Record user grouping | Yes                      | No   |
-| Uses feature flags   | Yes                      | Yes  |
-| Multivariate (A/B/n) | No                       | Yes  |
-
-- [Implementing an A/B experiment using `Experimentation Module`](experimentation.md)
 - [Implementing an A/B/n experiment using GLEX](gitlab_experiment.md)
+- [Implementing an A/B experiment using `Experimentation Module`](experimentation.md)
 
 Historical Context: `Experimentation Module` was built iteratively with the needs that
 appeared while implementing Growth sub-department experiments, while GLEX was built
 with the findings of the team and an easier to use API.
+
+### Add new icons and illustrations for experiments
+
+Some experiments may require you to add custom icons or illustrations to our codebase.
+This process is lengthy and at this stage, the outcome of the experiment uncertain.
+Therefore, you should postpone this effort until the [experiment cleanup process](https://about.gitlab.com/handbook/engineering/development/growth/#experiment-cleanup-issue).
+
+We recommend the following workflow:
+
+1. Add an icon or illustration as an `.svg` file in the `/app/assets/images` (or EE) path in the GitLab repository.
+1. Use `image_tag` or `image_path` to render it via the asset pipeline.
+1. **If the experiment is a success**, designers add the new icon or illustration to the Pajamas UI kit as part of the cleanup process.
+   Engineers can then add it to the [SVG library](https://gitlab-org.gitlab.io/gitlab-svgs/) and modify the implementation based on the
+   [Frontend Development Guidelines](../fe_guide/icons.md#usage-in-hamlrails-2).