Add latest changes from gitlab-org/gitlab@13-8-stable-eev13.8.0-rc42

1 files changed, 46 insertions, 0 deletions

diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md
index d0e89400d88..63ea84e42c9 100644
--- a/doc/user/project/code_owners.md
+++ b/doc/user/project/code_owners.md
@@ -225,6 +225,52 @@ the rules for "Groups" and "Documentation" sections:
 
 ![MR widget - Sectional Code Owners](img/sectional_code_owners_v13.2.png)
 
+#### Optional Code Owners Sections **(PREMIUM)**
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.8 behind a feature flag, enabled by default.
+
+When you want to make a certain section optional, you can do so by adding a code owners section prepended with the caret `^` character. Approvals from owners listed in the section will **not** be required. For example:
+
+```plaintext
+[Documentation]
+*.md @root
+
+[Ruby]
+*.rb @root
+
+^[Go]
+*.go @root
+```
+
+The optional code owners section will be displayed in merge requests under the **Approval Rules** area:
+
+![MR widget - Optional Code Owners Sections](img/optional_code_owners_sections_v13_8.png)
+
+If a section is duplicated in the file, and one of them is marked as optional and the other isn't, the requirement prevails. 
+
+For example, the code owners of the "Documentation" section below will still be required to approve merge requests: 
+
+```plaintext
+[Documentation]
+*.md @root
+
+[Ruby]
+*.rb @root
+
+^[Go]
+*.go @root
+
+^[Documentation]
+*.txt @root
+```
+
+Optional sections in the code owners file are currently treated as optional only
+when changes are submitted via merge requests. If a change is submitted directly
+to the protected branch, approval from code owners will still be required, even if the
+section is marked as optional. We plan to change this in a
+[future release](https://gitlab.com/gitlab-org/gitlab/-/issues/297638),
+where direct pushes to the protected branch will be allowed for sections marked as optional.
+
 ## Example `CODEOWNERS` file
 
 ```plaintext