Add documentation for Sectional Code Owners feature

doc/user/project/code_owners.md

@@ -22,7 +22,7 @@ who is responsible for each file or path.
 
 ## Why is this useful?
 
-Code Owners allows for a version controlled single source of
+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. Code Owners can be
 utilized in the merge request approval process which can streamline
@@ -38,18 +38,18 @@ approval.
 
 You can use a `CODEOWNERS` file to specify users or
 [shared groups](members/share_project_with_groups.md)
-that are responsible for certain files in a repository.
+that are responsible for specific files and directories in a repository.
 
-You can choose and add the `CODEOWNERS` file in three places:
+You can choose to add the `CODEOWNERS` file in three places:
 
 - 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
+The `CODEOWNERS` file is scoped to a branch, which means that as
+new files are introduced, the user adding the new content can
 specify themselves as a code owner, all before the new changes
-get merged to the default branch.
+get merged to the target branch.
 
 When a file matches multiple entries in the `CODEOWNERS` file,
 the users from last pattern matching the file are displayed on the
@@ -67,7 +67,7 @@ The user that would show for `README.md` would be `@user2`.
 
 ## Approvals by Code Owners
 
-Once you've set Code Owners to a project, you can configure it to
+Once you've added Code Owners to a project, you can configure it to
 be used for merge request approvals:
 
 - As [merge request eligible approvers](merge_requests/merge_request_approvals.md#code-owners-as-eligible-approvers).
@@ -81,7 +81,7 @@ Once set, Code Owners are displayed in merge requests widgets:
 
 ![MR widget - Code Owners](img/code_owners_mr_widget_v12_4.png)
 
-While the `CODEOWNERS` file can be used in addition to Merge Request [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules)
+While the `CODEOWNERS` file can be used in addition to Merge Request [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules),
 it can also be used as the sole driver of merge request approvals
 (without using [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules)).
 To do so, create the file in one of the three locations specified above and
@@ -89,28 +89,38 @@ set the code owners as required approvers for [protected branches](protected_bra
 Use [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files)
 to specify the actual owners and granular permissions.
 
-Using Code Owners in conjunction with [Protected Branches Approvals](protected_branches.md#protected-branches-approval-by-code-owners-premium)
-will prevent any user who is not specified in the `CODEOWNERS` file from pushing changes
-for the specified files/paths, even if their role is included in the **Allowed to push** column.
-This allows for a more inclusive push strategy, as administrators don't have to restrict developers
-from pushing directly to the protected branch, but can restrict pushing to certain
-files where a review by Code Owners is required.
+Using Code Owners in conjunction with [Protected Branches](protected_branches.md#protected-branches-approval-by-code-owners-premium)
+will prevent any user who is not specified in the `CODEOWNERS` file from pushing
+changes for the specified files/paths, even if their role is included in the
+**Allowed to push** column. This allows for a more inclusive push strategy, as
+administrators don't have to restrict developers from pushing directly to the
+protected branch, but can restrict pushing to certain files where a review by
+Code Owners is required.
 
 ## 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 the `@username` or email of one
-or more users or by the `@name` of one or more groups that should
-be owners of the file. Groups must be added as [members of the project](members/index.md),
+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.
+
+Groups must be added as [members of the project](members/index.md),
 or they will be ignored.
 
-Starting in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/32432), you can now specify
-groups or subgroups from the project's group hierarchy as potential code owners.
+Starting in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/32432),
+you can additionally specify groups or subgroups from the project's upper group
+hierarchy as potential code owners, without having to invite them specifically
+to the project. Groups outside the project's hierarchy or children beneath the
+hierarchy must still be explicitly invited to the project in order to show as
+Code Owners.
 
-For example, consider the following hierarchy for a given project:
+For example, consider the following hierarchy for the example project
+`example_project`:
 
 ```plaintext
-group >> sub-group >> sub-subgroup >> myproject >> file.md
+group >> sub-group >> sub-subgroup >> example_project >> file.md
 ```
 
 Any of the following groups would be eligible to be specified as code owners:
@@ -119,7 +129,8 @@ Any of the following groups would be eligible to be specified as code owners:
 - `@group/sub-group`
 - `@group/sub-group/sub-subgroup`
 
-In addition, any groups that have been invited to the project using the **Members** tool will also be recognized as eligible code owners.
+In addition, any groups that have been invited to the project using the
+**Members** tool will also be recognized as eligible code owners.
 
 The order in which the paths are defined is significant: the last
 pattern that matches a given path will be used to find the code
@@ -129,7 +140,98 @@ Starting a line with a `#` indicates a comment. This needs to be
 escaped using `\#` to address files for which the name starts with a
 `#`.
 
-Example `CODEOWNERS` file:
+### Code Owners Sections **(PREMIUM)**
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2.
+> - It's deployed behind a feature flag, enabled by default.
+> - It's enabled on GitLab.com.
+> - It can be enabled or disabled per-project.
+> - It's recommended for production use.
+> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-code-owner-sections-core-only). **(CORE ONLY)**
+
+Code Owner rules can be grouped into named sections. This allows for better
+organization of broader categories of Code Owner rules to be applied.
+Additionally, the usual guidance that only the last pattern matching the file is
+applied is expanded such that the last pattern matching _for each section_ is
+applied.
+
+For example, in a large organization, independent teams may have a common interest
+in parts of the application, for instance, a payment processing company may have
+"development", "security", and "compliance" teams looking after common parts of
+the codebase. All three teams may need to approve changes. Although approval rules
+make this possible, they apply to every merge request. Also, while Code Owners are
+applied based on which files are changed, only one CODEOWNERS pattern can match per
+file path.
+
+Using `CODEOWNERS` sections allows multiple teams that only need to approve certain
+changes, to set their own independent patterns by specifying discrete sections in the
+`CODEOWNERS` file. The section rules may be used for shared paths so that multiple
+teams can be added as reviewers.
+
+Sections can be added to `CODEOWNERS` files as a new line with the name of the
+section inside square brackets. Every entry following it is assigned to that
+section. The following example would create 2 Code Owner rules for the "README
+Owners" section:
+
+```plaintext
+[README Owners]
+README.md @user1 @user 2
+internal/README.md @user2
+```
+
+Multiple sections can be used, even with matching file or directory patterns.
+Reusing the same section name will group the results together under the same
+section, with the most specific rule or last matching pattern being used. For
+example, consider the following entries in a `CODEOWNERS` file:
+
+```plaintext
+[Documentation]
+ee/docs    @gl-docs
+docs       @gl-docs
+
+[Database]
+README.md  @gl-database
+model/db   @gl-database
+
+[DOCUMENTATION]
+README.md  @gl-docs
+```
+
+This will result in 3 entries under the "Documentation" section header, and 2
+entries under "Database". Case is not considered when combining sections, so in
+this example, entries defined under the sections "Documentation" and
+"DOCUMENTATION" would be combined into one, using the case of the first instance
+of the section encountered in the file.
+
+When assigned to a section, each code owner rule displayed in merge requests
+widget is sorted under a "section" label. In the screenshot below, we can see
+the rules for "Groups" and "Documentation" sections:
+
+![MR widget - Sectional Code Owners](img/sectional_code_owners_v13.2.png)
+
+#### Enable or disable Code Owner Sections **(CORE ONLY)**
+
+Sections is under development but ready for production use.
+It is deployed behind a feature flag that is **enabled by default**.
+[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md)
+can opt to disable it for your instance.
+
+To disable it:
+
+```ruby
+Feature.disable(:sectional_codeowners)
+```
+
+To enable it:
+
+```ruby
+Feature.enable(:sectional_codeowners)
+```
+
+CAUTION: **Caution:**
+Disabling Sections will **not** refresh Code Owner Approval Rules on existing merge requests.
+
+## Example `CODEOWNERS` file
 
 ```plaintext
 # This is an example of a code owners file
@@ -185,4 +287,17 @@ lib/ @lib-owner
 
 # If the path contains spaces, these need to be escaped like this:
 path\ with\ spaces/ @space-owner
+
+# Code Owners section:
+[Documentation]
+ee/docs    @gl-docs
+docs       @gl-docs
+
+[Database]
+README.md  @gl-database
+model/db   @gl-database
+
+# This section will be joined with the [Documentation] section previously defined:
+[DOCUMENTATION]
+README.md  @gl-docs
 ```