Merge branch 'docs-codeowners-update' into 'master'

Docs: update Code Owners

Closes #9517

See merge request gitlab-org/gitlab!18683

doc/user/project/code_owners.md

+---
+type: reference
+---
+
 # Code Owners **(STARTER)**
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/6916)
 in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3.
 > - [Support for group namespaces](https://gitlab.com/gitlab-org/gitlab-foss/issues/53182) added in GitLab Starter 12.1.
+> - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/issues/4418) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.9.
 
 You can use a `CODEOWNERS` file to specify users or
 [shared groups](members/share_project_with_groups.md)
@@ -10,9 +15,9 @@ that are responsible for certain files in a repository.
 
 You can choose and add the `CODEOWNERS` file in three places:
 
-- to the root directory of the repository
-- inside the `.gitlab/` directory
-- inside the `docs/` directory
+- To the root directory of the repository
+- Inside the `.gitlab/` directory
+- Inside the `docs/` directory
 
 The `CODEOWNERS` file is scoped to a branch, which means that with the
 introduction of new files, the person adding the new content can
@@ -23,6 +28,18 @@ When a file matches multiple entries in the `CODEOWNERS` file,
 the users from all entries are displayed on the blob page of
 the given file.
 
+## Approvals by Code Owners
+
+Once you've set Code Owners to a project, you can configure it to
+receive approvals:
+
+- As [merge request eligible approvers](merge_requests/merge_request_approvals.md#code-owners-as-eligible-approvers-starter). **(STARTER)**
+- As required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners-premium). **(PREMIUM)**
+
+Once set, Code Owners are displayed in merge requests widgets:
+
+![MR widget - Code Owners](img/code_owners_mr_widget_v12_4.png)
+
 ## The syntax of Code Owners files
 
 Files can be specified using the same kind of patterns you would use

doc/user/project/merge_requests/merge_request_approvals.md

@@ -101,7 +101,7 @@ any [eligible approver](#eligible-approvers) may approve.
 The following can approve merge requests:
 
 - Users being added as approvers at project or merge request level.
-- [Code owners](../code_owners.md) related to the merge request ([introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/7933) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.5).
+- [Code owners](#code-owners-as-eligible-approvers-starter) to the files changed by the merge request.
 
 An individual user can be added as an approver for a project if they are a member of:
 
@@ -119,6 +119,31 @@ if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-thei
 and [**Prevent committers approval**](#prevent-approval-of-merge-requests-by-their-committers) (disabled by default)
 are enabled on the project settings.
 
+### Code Owners as eligible approvers **(STARTER)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/7933) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.5.
+
+Once you've added [Code Owners](../code_owners.md) to your
+repository, the owners to the corresponding files will become
+eligible approvers, together with members with Developer or
+higher permissions.
+
+To enable this merge request approval rule:
+
+1. Navigate to your project's **Settings > General** and expand
+**Merge request approvals**.
+1. Locate **All members with Developer role or higher and code owners (if any)** and click **Edit** to choose the number of approvals required.
+
+![MR approvals by Code Owners](img/mr_approvals_by_code_owners_v12_4.png)
+
+Once set, merge requests can only be merged once approved by the
+number of approvals you've set. GitLab will accept approvals from
+users with Developer or higher permissions, as well as by Code Owners,
+indistinguishably.
+
+Alternatively, you can **require**
+[Code Owner's approvals for Protected Branches](../protected_branches.md#protected-branches-approval-by-code-owners-premium). **(PREMIUM)**
+
 ### Implicit approvers
 
 If the number of required approvals is greater than the number of approvers,
@@ -162,26 +187,6 @@ are other conditions that may block it, such as merge conflicts,
 [pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved)
 or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md).
 
-## Code Owners approvals **(PREMIUM)**
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4418) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.9.
-
-It is possible to require at least one approval for each entry in the
-[`CODEOWNERS` file](../code_owners.md) that matches a file changed in
-the merge request. To enable this feature:
-
-1. Navigate to your project's **Settings > General** and expand
-   **Merge request approvals**.
-1. Tick the **Require approval from code owners** checkbox.
-1. Click **Save changes**.
-
-When this feature is enabled, all merge requests will need approval
-from one code owner per matched rule before it can be merged.
-
-NOTE: **Note:** Only the `CODEOWNERS` file on the default branch is evaluated for
-Merge Request approvals. If `CODEOWNERS` is changed on a non-default branch, those
-changes will not affect approvals until merged to the default branch.
-
 ## Overriding the merge request approvals default settings
 
 > Introduced in GitLab Enterprise Edition 9.4.

doc/user/project/protected_branches.md

@@ -86,20 +86,6 @@ Click **Protect** and the branch will appear in the "Protected branch" list.
 
 ![Roles and users list](img/protected_branches_select_roles_and_users_list.png)
 
-## Code Owners approvals **(PREMIUM)**
-
-It is possible to require at least one approval for each entry in the
-[`CODEOWNERS` file](code_owners.md) that matches a file changed in
-the merge request. To enable this feature:
-
-1. Toggle the **Require approval from code owners** slider.
-
-1. Click **Protect**.
-
-When this feature is enabled, all merge requests need approval
-from one code owner per matched rule before they can be merged. Additionally,
-pushes to the protected branch are denied if a rule is matched.
-
 ## Wildcard protected branches
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/4665) in GitLab 8.10.
@@ -166,6 +152,35 @@ Deleting a protected branch is only allowed via the web interface, not via Git.
 This means that you can't accidentally delete a protected branch from your
 command line or a Git client application.
 
+## Protected Branches approval by Code Owners **(PREMIUM)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13251) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4.
+
+It is possible to require at least one approval by a
+[Code Owner](code_owners.md) to a file changed by the
+merge request. You can either set Code Owners approvals
+at the time you protect a new branch, or set it to a branch
+already protected, as described below.
+
+To protect a new branch and enable Code Owner's approval:
+
+1. Navigate to your project's **Settings > Repository** and expand **Protected branches**.
+1. Scroll down to **Protect a branch**, select a **Branch** or wildcard you'd like to protect, select who's **Allowed to merge** and **Allowed to push**, and toggle the **Require approval from code owners** slider.
+1. Click **Protect**.
+
+![Code Owners approval - new protected branch](img/code_owners_approval_new_protected_branch_v12_4.png)
+
+To enable Code Owner's approval to branches already protected:
+
+1. Navigate to your project's **Settings > Repository** and expand **Protected branches**.
+1. Scroll down to **Protected branch** and toggle the **Code owner approval** slider for the chosen branch.
+
+![Code Owners approval - branch already protected](img/code_owners_approval_protected_branch_v12_4.png)
+
+When enabled, all merge requests targeting these branches will require approval
+by a Code Owner per matched rule before they can be merged.
+Additionally, direct pushes to the protected branch are denied if a rule is matched.
+
 ## Running pipelines on protected branches
 
 The permission to merge or push to protected branches is used to define if a user can