Add latest changes from gitlab-org/gitlab@master

3 files changed, 58 insertions, 66 deletions

diff --git a/doc/development/features_inside_dot_gitlab.md b/doc/development/features_inside_dot_gitlab.md
index 36b9064bbc4..4631ab3a471 100644
--- a/doc/development/features_inside_dot_gitlab.md
+++ b/doc/development/features_inside_dot_gitlab.md
@@ -13,7 +13,7 @@ When implementing new features, please refer to these existing features to avoid
 - [Issue Templates](../user/project/description_templates.md#create-an-issue-template): `.gitlab/issue_templates/`.
 - [Merge Request Templates](../user/project/description_templates.md#create-a-merge-request-template): `.gitlab/merge_request_templates/`.
 - [GitLab Kubernetes Agents](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/configuration_repository.md#layout): `.gitlab/agents/`.
-- [CODEOWNERS](../user/project/code_owners.md#how-to-set-up-code-owners): `.gitlab/CODEOWNERS`.
+- [CODEOWNERS](../user/project/code_owners.md#set-up-code-owners): `.gitlab/CODEOWNERS`.
 - [Route Maps](../ci/review_apps/#route-maps): `.gitlab/route-map.yml`.
 - [Customize Auto DevOps Helm Values](../topics/autodevops/customize.md#customize-values-for-helm-chart): `.gitlab/auto-deploy-values.yaml`.
 - [GitLab managed apps CI/CD](../user/clusters/applications.md#usage): `.gitlab/managed-apps/config.yaml`.
diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md
index 737a068b5e7..773d41947e2 100644
--- a/doc/user/group/value_stream_analytics/index.md
+++ b/doc/user/group/value_stream_analytics/index.md
@@ -65,7 +65,8 @@ To filter results:
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 12.4.
 
-GitLab provides the ability to filter analytics based on a date range. Data is shown for workflow items created during the selected date range. To filter results:
+GitLab provides the ability to filter analytics based on a date range.
+Data is shown for workflow items created during the selected date range. To filter results:
 
 1. Select a group.
 1. Optionally select a project.
@@ -82,13 +83,16 @@ The "Time" metrics near the top of the page are measured as follows:
 The "Recent Activity" metrics near the top of the page are measured as follows:
 
 - **New Issues:** the number of issues created in the date range.
-- **Deploys:** the number of deployments to production (1) in the date range.
-- **Deployment Frequency:** the average number of deployments to production (1) per day in the date range.
+- **Deploys:** the number of deployments <sup>1</sup> to production <sup>2</sup> in the date range.
+- **Deployment Frequency:** the average number of deployments <sup>1</sup> to production <sup>2</sup>
+   per day in the date range.
 
-(1) To give a more accurate representation of deployments that actually completed successfully,
-the calculation for these two metrics changed in GitLab 13.9 from using the time a deployment was
-created to the time a deployment finished. If you were referencing this metric prior to 13.9, please
-keep this slight change in mind.
+1. To give a more accurate representation of deployments that actually completed successfully,
+   the calculation for these two metrics changed in GitLab 13.9 from using the time a deployment was
+   created to the time a deployment finished. If you were referencing this metric prior to 13.9, please
+   keep this slight change in mind.
+1. To see deployment metrics, you must have a
+   [production environment configured](../../../ci/environments/index.md#deployment-tier-of-environments).
 
 You can learn more about these metrics in our [analytics definitions](../../analytics/index.md).
 
@@ -105,7 +109,7 @@ Each stage of Value Stream Analytics is further described in the table below.
 | **Stage** | **Description** |
 | --------- | --------------- |
 | Issue     | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whatever comes first. The label is tracked only if it already has an [Issue Board list](../../project/issue_board.md) created for it. |
-| Plan      | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. The very first commit of the branch is the one that triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch needs to contain the related issue number (e.g., `#42`). If none of the commits in the branch mention the related issue number, it is not considered to the measurement time of the stage. |
+| Plan      | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. The very first commit of the branch is the one that triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch needs to contain the related issue number (for example, `#42`). If none of the commits in the branch mention the related issue number, it is not considered to the measurement time of the stage. |
 | Code      | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR) related to that commit. The key to keep the process tracked is to include the [issue closing pattern](../../project/issues/managing_issues.md#closing-issues-automatically) to the description of the merge request (for example, `Closes #xxx`, where `xxx` is the number of the issue related to this merge request). If the closing pattern is not present, then the calculation takes the creation time of the first commit in the merge request as the start time. |
 | Test      | Measures the median time to run the entire pipeline for that project. It's related to the time GitLab CI/CD takes to run every job for the commits pushed to that merge request defined in the previous stage. It is basically the start->finish time for all pipelines. |
 | Review    | Measures the median time taken to review the merge request that has a closing issue pattern, between its creation and until it's merged. |
@@ -121,7 +125,7 @@ How this works, behind the scenes:
    by the UI - default is 90 days). So it prohibits these pairs from being considered.
 1. For the remaining `<issue, merge request>` pairs, we check the information that
    we need for the stages, like issue creation date, merge request merge time,
-   etc.
+   and so on.
 
 To sum up, anything that doesn't follow [GitLab flow](../../../topics/gitlab_flow.md) is not tracked and the
 Value Stream Analytics dashboard does not present any data for:
@@ -144,7 +148,7 @@ You can change the name of a project environment in your GitLab CI/CD configurat
 
 ## Example workflow
 
-Below is a simple fictional workflow of a single cycle that happens in a
+Below is an example workflow of a single cycle that happens in a
 single day through all noted stages. Note that if a stage does not include a start
 and a stop time, its data is not included in the median time. It is assumed that
 milestones are created and a CI for testing and setting environments is configured.
@@ -159,7 +163,8 @@ environments is configured.
    12:00.
 1. Make a second commit to the branch which mentions the issue number at 12.30
    (stop of **Plan** stage / start of **Code** stage).
-1. Push branch and create a merge request that contains the [issue closing pattern](../../project/issues/managing_issues.md#closing-issues-automatically)
+1. Push branch and create a merge request that contains the
+   [issue closing pattern](../../project/issues/managing_issues.md#closing-issues-automatically)
    in its description at 14:00 (stop of **Code** stage / start of **Test** and
    **Review** stages).
 1. The CI starts running your scripts defined in [`.gitlab-ci.yml`](../../../ci/yaml/index.md) and
@@ -185,7 +190,7 @@ A few notes:
   commit doesn't mention the issue number, you can do this later in any commit
   of the branch you are working on.
 - You can see that the **Test** stage is not calculated to the overall time of
-  the cycle since it is included in the **Review** process (every MR should be
+  the cycle, because it is included in the **Review** process (every MR should be
   tested).
 - The example above was just **one cycle** of the seven stages. Add multiple
   cycles, calculate their median time and the result is what the dashboard of
@@ -381,7 +386,7 @@ This chart visually depicts the average number of days it takes for cycles to be
 
 This chart uses the global page filters for displaying data based on the selected
 group, projects, and time frame. In addition, specific stages can be selected
-from within the chart itself.
+from the chart itself.
 
 The chart data is limited to the last 500 items.
 
diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md
index 790836ddbd9..2a60c06814b 100644
--- a/doc/user/project/code_owners.md
+++ b/doc/user/project/code_owners.md
@@ -11,56 +11,56 @@ type: reference
 > - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in GitLab Premium 11.9.
 > - Moved to GitLab Premium in 13.9.
 
-## Introduction
+Code Owners define who owns specific files or paths in a repository.
+You can require that Code Owners approve a merge request before it's merged.
 
-When contributing to a project, it can often be difficult
-to find out who should review or approve merge requests.
-Additionally, if you have a question over a specific file or
-code block, it may be difficult to know who to find the answer from.
+Code Owners help you determine who should review or approve merge requests.
+If you have a question about a file or feature, Code Owners
+can help you find someone who knows the answer.
 
-The GitLab Code Owners feature defines who owns specific
-files or paths in a repository, allowing other users to understand
-who is responsible for each file or path.
+If you don't want to use Code Owners for approvals, you can
+[configure rules](merge_requests/approvals/rules.md) instead.
 
-As an alternative to using Code Owners for approvals, you can instead
-[configure rules](merge_requests/approvals/rules.md).
+## Set up Code Owners
 
-## Why is this useful?
+You can specify users or [shared groups](members/share_project_with_groups.md)
+that are responsible for specific files and directories in a repository.
 
-Code Owners allows for a version controlled, single source of
-truth file outlining the exact GitLab users or groups that
-own certain files or paths in a repository. In larger organizations
-or popular open source projects, Code Owners can help you understand
-who to contact if you have a question about a specific portion of
-the codebase. Code Owners can also streamline the merge request approval
-process, identifying the most relevant reviewers and approvers for a
-given change.
+To set up Code Owners:
 
-## How to set up Code Owners
+1. Choose the location where you want to specify Code Owners:
+   - In the root directory of the repository
+   - In the `.gitlab/` directory
+   - In the `docs/` directory
 
-You can use a `CODEOWNERS` file to specify users or
-[shared groups](members/share_project_with_groups.md)
-that are responsible for specific files and directories in a repository.
+1. In that location, create a file named `CODEOWNERS`.
+
+1. In the file, enter text that follows one of these patterns:
+
+   ```plaintext
+   # A member as Code Owner of a file
+   filename @username
+
+   # A member as Code Owner of a directory
+   directory @username
 
-You can choose to add the `CODEOWNERS` file in three places:
+   # All group members as Code Owners of a file
+   filename @groupname
 
-- To the root directory of the repository
-- Inside the `.gitlab/` directory
-- Inside the `docs/` directory
+   # All group members as Code Owners of a directory
+   directory @groupname
+   ```
 
-The `CODEOWNERS` file is valid for the branch where it lives. For example, if you change the code owners
-in a feature branch, the changes aren't valid in the main branch until the feature branch is merged.
+The Code Owners are displayed in the UI by the files or directory they apply to.
+These owners apply to this branch only. When you add new files to the repository,
+you should update the `CODEOWNERS` file.
 
-If you introduce new files to your repository and you want to identify the code owners for that file,
-you must update `CODEOWNERS` accordingly. If you update the code owners when you are adding the files (in the same
-branch), GitLab counts the owners as soon as the branch is merged. If
-you don't, you can do that later, but your new files don't belong to anyone until you update your
-`CODEOWNERS` file in the TARGET branch.
+## When a file matches multiple `CODEOWNERS` entries
 
 When a file matches multiple entries in the `CODEOWNERS` file,
-the users from last pattern matching the file are displayed on the
-blob page of the given file. For example, you have the following
-`CODEOWNERS` file:
+the users from last pattern matching the file are used.
+
+For example, in the following `CODEOWNERS` file:
 
 ```plaintext
 README.md @user1
@@ -94,7 +94,7 @@ without using [Approval Rules](merge_requests/approvals/rules.md):
 1. Create the file in one of the three locations specified above.
 1. Set the code owners as required approvers for
    [protected branches](protected_branches.md#require-code-owner-approval-on-a-protected-branch).
-1. Use [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files)
+1. Use [the syntax of Code Owners files](code_owners.md)
    to specify the actual owners and granular permissions.
 
 Using Code Owners in conjunction with [protected branches](protected_branches.md#require-code-owner-approval-on-a-protected-branch)
@@ -107,20 +107,7 @@ Code Owners is required.
 
 [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5, users and groups who are allowed to push to protected branches do not require a merge request to merge their feature branches. Thus, they can skip merge request approval rules, Code Owners included.
 
-## The syntax of Code Owners files
-
-Files can be specified using the same kind of patterns you would use
-in the `.gitignore` file followed by one or more of:
-
-- A user's `@username`.
-- A user's email address.
-- The `@name` of one or more groups that should be owners of the file.
-- Lines starting with `#` are ignored.
-
-The path definition order is significant: the last pattern
-matching a given path is used to find the code owners.
-
-### Groups as Code Owners
+## Groups as Code Owners
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) in GitLab 12.1.
 > - Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0.