Initial revision of merge request approval settings page for CTRT

doc/api/merge_request_approvals.md

@@ -1068,7 +1068,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approve
 | `id`                | integer | yes      | The ID of a project     |
 | `merge_request_iid` | integer | yes      | The IID of MR           |
 | `sha`               | string  | no       | The HEAD of the MR      |
-| `approval_password` **(PREMIUM)** | string  | no      | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/approvals/settings.md#require-authentication-when-approving-a-merge-request) is enabled in the project settings. |
+| `approval_password` **(PREMIUM)** | string  | no      | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/approvals/settings.md#require-authentication-for-approvals) is enabled in the project settings. |
 
 The `sha` parameter works in the same way as
 when [accepting a merge request](merge_requests.md#accept-mr): if it is passed, then it must

doc/user/compliance/compliance_dashboard/index.md

@@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36524) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.8.
 
-The Compliance Dashboard gives you the ability to see a group's Merge Request activity
+The Compliance Dashboard gives you the ability to see a group's merge request activity
 by providing a high-level view for all projects in the group. For example, code approved
 for merging into production.
 
@@ -28,10 +28,10 @@ This feature is for people who care about the compliance status of projects with
 
 You can use the dashboard to:
 
-- Get an overview of the latest Merge Request for each project.
-- See if Merge Requests were approved and by whom.
-- See Merge Request authors.
-- See the latest [CI Pipeline](../../../ci/pipelines/index.md) result for each Merge Request.
+- Get an overview of the latest merge request for each project.
+- See if merge requests were approved and by whom.
+- See merge request authors.
+- See the latest [CI Pipeline](../../../ci/pipelines/index.md) result for each merge request.
 
 ## Permissions
 
@@ -42,25 +42,25 @@ You can use the dashboard to:
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217939) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3.
 
-We support a separation of duties policy between users who create and approve Merge Requests.
+We support a separation of duties policy between users who create and approve merge requests.
 The approval status column can help you identify violations of this policy.
 Our criteria for the separation of duties is as follows:
 
-- [A Merge Request author is **not** allowed to approve their Merge Request](../../project/merge_requests/approvals/settings.md#allowing-merge-request-authors-to-approve-their-own-merge-requests)
-- [A Merge Request committer is **not** allowed to approve a Merge Request they have added commits to](../../project/merge_requests/approvals/settings.md#prevent-approval-of-merge-requests-by-their-committers)
-- [The minimum number of approvals required to merge a Merge Request is **at least** two](../../project/merge_requests/approvals/rules.md)
+- [A merge request author is **not** allowed to approve their merge request](../../project/merge_requests/approvals/settings.md#prevent-authors-from-approving-their-own-work)
+- [A merge request committer is **not** allowed to approve a merge request they have added commits to](../../project/merge_requests/approvals/settings.md#prevent-committers-from-approving-their-own-work)
+- [The minimum number of approvals required to merge a merge request is **at least** two](../../project/merge_requests/approvals/rules.md)
 
-The "Approval status" column shows you, at a glance, whether a Merge Request is complying with the above.
+The "Approval status" column shows you, at a glance, whether a merge request is complying with the above.
 This column has four states:
 
 | State | Description |
 |:------|:------------|
-| Empty | The Merge Request approval status is unknown |
-| ![Failed](img/failed_icon_v13_3.png) | The Merge Request **does not** comply with any of the above criteria |
-| ![Warning](img/warning_icon_v13_3.png) | The Merge Request complies with **some** of the above criteria |
-| ![Success](img/success_icon_v13_3.png) | The Merge Request complies with **all** of the above criteria |
+| Empty | The merge request approval status is unknown |
+| ![Failed](img/failed_icon_v13_3.png) | The merge request **does not** comply with any of the above criteria |
+| ![Warning](img/warning_icon_v13_3.png) | The merge request complies with **some** of the above criteria |
+| ![Success](img/success_icon_v13_3.png) | The merge request complies with **all** of the above criteria |
 
-If you do not see the success icon in your Compliance dashboard; please review the above criteria for the Merge Requests
+If you do not see the success icon in your Compliance dashboard; please review the above criteria for the merge requests
 project to make sure it complies with the separation of duties described above.
 
 ## Chain of Custody report **(ULTIMATE)**

doc/user/project/merge_requests/approvals/index.md

@@ -26,19 +26,20 @@ rules to define what types of users can approve work. Some examples of rules you
 
 - Users with specific permissions can always approve work.
 - [Code owners](../../code_owners.md) can approve work for files they own.
-- Users with specific permissions can approve work, even if they don't have merge rights
+- Users with specific permissions can approve work,
+  [even if they don't have merge rights](rules.md#merge-request-approval-segregation-of-duties)
   to the repository.
 - Users with specific permissions can be allowed or denied the ability
-  to override approval rules on a specific merge request.
+  to [override approval rules on a specific merge request](rules.md#edit-or-override-merge-request-approval-rules).
 
 You can also configure additional [settings for merge request approvals](settings.md)
 for more control of the level of oversight and security your project needs, including:
 
-- Prevent users from overriding a merge request approval rule.
-- Reset approvals when new code is pushed.
-- Allow (or disallow) authors and committers to approve their own merge requests.
-- Require password authentication when approving.
-- Require security team approval.
+- [Prevent users from overriding a merge request approval rule.](settings.md#prevent-overrides-of-default-approvals)
+- [Reset approvals when new code is pushed.](settings.md#reset-approvals-on-push)
+- Allow (or disallow) [authors and committers](settings.md) to approve their own merge requests.
+- [Require password authentication when approving.](settings.md#require-authentication-for-approvals)
+- [Require security team approval.](settings.md#security-approvals-in-merge-requests)
 
 You can configure your merge request approval rules and settings through the GitLab
 user interface or [with the API](../../../../api/merge_request_approvals.md).
@@ -63,10 +64,10 @@ such as merge conflicts, [pending discussions](../../../discussions/index.md#onl
 or a [failed CI/CD pipeline](../merge_when_pipeline_succeeds.md).
 
 To prevent merge request authors from approving their own merge requests,
-enable [**Prevent author approval**](settings.md#allowing-merge-request-authors-to-approve-their-own-merge-requests)
+enable [**Prevent author approval**](settings.md#prevent-authors-from-approving-their-own-work)
 in your project's settings.
 
-If you enable [approval rule overrides](settings.md#prevent-overriding-default-approvals),
+If you enable [approval rule overrides](settings.md#prevent-overrides-of-default-approvals),
 merge requests created before a change to default approval rules are not affected.
 The only exceptions are changes to the [target branch](rules.md#approvals-for-protected-branches)
 of the rule.
@@ -118,7 +119,7 @@ You can modify your external approval rules
 
 The lack of an external approval doesn't block the merging of a merge request.
 
-When [approval rule overrides](settings.md#prevent-overriding-default-approvals) are allowed,
+When [approval rule overrides](settings.md#prevent-overrides-of-default-approvals) are allowed,
 changes to default approval rules will **not** be applied to existing
 merge requests, except for changes to the [target branch](rules.md#approvals-for-protected-branches)
 of the rule.

doc/user/project/merge_requests/approvals/rules.md

@@ -49,7 +49,7 @@ Users of GitLab Premium and higher tiers can create [additional approval rules](
 Your configuration for approval rule overrides determines if the new rule is applied
 to existing merge requests:
 
-- If [approval rule overrides](settings.md#prevent-overriding-default-approvals) are allowed,
+- If [approval rule overrides](settings.md#prevent-overrides-of-default-approvals) are allowed,
   changes to these default rules are not applied to existing merge requests, except for
   changes to the [target branch](#approvals-for-protected-branches) of the rule.
 - If approval rule overrides are not allowed, all changes to default rules
@@ -138,10 +138,10 @@ approve in these ways:
   counts as one approver, and not two.
 - Merge request authors do not count as eligible approvers on their own merge requests by default.
   To change this behavior, disable the
-  [**Prevent author approval**](settings.md#allowing-merge-request-authors-to-approve-their-own-merge-requests)
+  [**Prevent author approval**](settings.md#prevent-authors-from-approving-their-own-work)
   project setting.
 - Committers to merge requests can approve a merge request. To change this behavior, enable the
-  [**Prevent committers approval**](settings.md#prevent-approval-of-merge-requests-by-their-committers)
+  [**Prevent committers approval**](settings.md#prevent-committers-from-approving-their-own-work)
   project setting.
 
 ### Code owners as eligible approvers
@@ -200,7 +200,7 @@ on a merge request, you can either add or remove approvers:
    1. Add or remove your desired approval rules.
    1. Select **Save changes**.
 
-Administrators can change the [merge request approvals settings](settings.md#prevent-overriding-default-approvals)
+Administrators can change the [merge request approvals settings](settings.md#prevent-overrides-of-default-approvals)
 to prevent users from overriding approval rules for merge requests.
 
 ## Configure optional approval rules

doc/user/project/merge_requests/approvals/settings.md

@@ -7,91 +7,119 @@ type: reference, concepts
 
 # Merge request approval settings
 
-The settings for merge request approvals are found by going to
-**Settings > General** and expanding **Merge request (MR) approvals**.
+You can configure the settings for [merge request approvals](index.md) to
+ensure the approval rules meet your use case. You can also configure
+[approval rules](rules.md), which define the number and type of users who must
+approve work before it's merged. Merge request approval settings define how
+those rules are applied as a merge request moves toward completion.
 
-## Prevent overriding default approvals
+## Edit merge request approval settings
 
-Regardless of the approval rules you choose for your project, users can edit them in every merge
-request, overriding the [rules you set as default](rules.md#add-an-approval-rule).
-To prevent that from happening:
+To view or edit merge request approval settings:
 
-1. Select the **Prevent users from modifying MR approval rules in merge requests.** checkbox.
-1. Click **Save changes**.
+1. Go to your project and select **Settings > General**.
+1. Expand **Merge request (MR) approvals**.
 
-### Resetting approvals on push
+In this section of general settings, you can configure the settings described
+on this page.
 
-You can force all approvals on a merge request to be removed when new commits are
-pushed to the source branch of the merge request. If disabled, approvals persist
-even if there are changes added to the merge request. To enable this feature:
+## Prevent overrides of default approvals
 
-1. Check the **Require new approvals when new commits are added to an MR.**
-   checkbox.
-1. Click **Save changes**.
+By default, users can override the approval rules you [create for a project](rules.md)
+on a per-merge request basis. If you don't want users to change approval rules
+on merge requests, you can disable this setting:
 
-NOTE:
-Approvals do not get reset when [rebasing a merge request](../fast_forward_merge.md)
-from the UI. However, approvals are reset if the target branch is changed.
+1. Go to your project and select **Settings > General**.
+1. Expand **Merge request (MR) approvals**.
+1. Select the **Prevent users from modifying MR approval rules in merge requests** checkbox.
+1. Select **Save changes**.
 
-### Allowing merge request authors to approve their own merge requests **(PREMIUM)**
+TODO This change affects all open merge requests.
+
+## Reset approvals on push
+
+By default, an approval on a merge request remains in place, even if you add more changes
+after the approval. If you want to remove all existing approvals on a merge request
+when more changes are added to it:
+
+1. Go to your project and select **Settings > General**.
+1. Expand **Merge request (MR) approvals**.
+1. Select the **Require new approvals when new commits are added to an MR** checkbox.
+1. Select **Save changes**.
+
+Approvals aren't reset when a merge request is [rebased from the UI](../fast_forward_merge.md)
+However, approvals are reset if the target branch is changed.
+
+## Prevent authors from approving their own work **(PREMIUM)**
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in GitLab 11.3.
 > - Moved to GitLab Premium in 13.9.
 
-By default, projects are configured to prevent merge requests from being approved by
-their own authors. To change this setting:
+By default, the author of a merge request cannot approve it. To change this setting:
 
-1. Go to your project's **Settings > General**, expand **Merge request (MR) approvals**.
-1. Uncheck the **Prevent MR approval by the author.** checkbox.
-1. Click **Save changes**.
+1. Go to your project and select **Settings > General**.
+1. Expand **Merge request (MR) approvals**.
+1. Clear the **Prevent MR approval by the author** checkbox.
+1. Select **Save changes**.
 
-Note that users can edit the approval rules in every merge request and override pre-defined settings unless it's set [**not to allow** overrides](#prevent-overriding-default-approvals).
+Authors can edit the approval rule in an individual merge request and override
+this setting, unless you configure one of these options:
 
-You can prevent authors from approving their own merge requests
-[at the instance level](../../../admin_area/merge_requests_approvals.md). When enabled,
-this setting is disabled on the project level, and not editable.
+- [Prevent overrides of default approvals](#prevent-overrides-of-default-approvals) at
+  the project level.
+- *(Self-managed instances only)* Prevent overrides of default approvals
+  [at the instance level](../../../admin_area/merge_requests_approvals.md). When configured
+  at the instance level, you can't edit this setting at the project or individual
+  merge request levels.
 
-### Prevent approval of merge requests by their committers **(PREMIUM)**
+## Prevent committers from approving their own work **(PREMIUM)**
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in GitLab 11.10.
 > - Moved to GitLab Premium in 13.9.
 
-You can prevent users who have committed to a merge request from approving it,
-though code authors can still approve. You can enable this feature
-[at the instance level](../../../admin_area/merge_requests_approvals.md), which
-disables changes to this feature at the project level. If you prefer to manage
-this feature at the project level, you can:
+By default, users who commit to a merge request can still approve it. At both
+the project level or [instance level](../../../admin_area/merge_requests_approvals.md)
+you can prevent committers from approving merge requests that are partially
+their own. To do this:
 
-1. Check the **Prevent MR approvals from users who make commits to the MR.** checkbox.
-   If this check box is disabled, this feature has been disabled
-   [at the instance level](../../../admin_area/merge_requests_approvals.md).
-1. Click **Save changes**.
+1. Go to your project and select **Settings > General**.
+1. Expand **Merge request (MR) approvals**.
+1. Select the **Prevent MR approvals from users who make commits to the MR** checkbox.
+   If this checkbox is cleared, an administrator has disabled it
+   [at the instance level](../../../admin_area/merge_requests_approvals.md), and
+   it can't be changed at the project level.
+1. Select **Save changes**.
 
-Read the official Git documentation for an explanation of the
-[differences between authors and committers](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History).
+Even with this configuration, [code owners](../../code_owners.md) who contribute
+to a merge request can approve merge requests that affect files they own.
 
-### Require authentication when approving a merge request
+To learn more about the [differences between authors and committers](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History),
+read the official Git documentation for an explanation.
+
+## Require authentication for approvals
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in GitLab 12.0.
 > - Moved to GitLab Premium in 13.9.
 
-NOTE:
-To require authentication when approving a merge request, you must enable
-**Password authentication enabled for web interface** under [sign-in restrictions](../../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled).
-in the Admin Area.
-
-You can force the approver to enter a password in order to authenticate before adding
-the approval. This enables an Electronic Signature for approvals such as the one defined
-by [CFR Part 11](https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfcfr/CFRSearch.cfm?CFRPart=11&showFR=1&subpartNode=21:1.0.1.1.8.3)).
-To enable this feature:
+You can force potential approvers to first authenticate with a password. This
+permission enables an electronic signature for approvals, such as the one defined by
+[Code of Federal Regulations (CFR) Part 11](https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfcfr/CFRSearch.cfm?CFRPart=11&showFR=1&subpartNode=21:1.0.1.1.8.3)):
 
-1. Check the **Require user password for approvals.** checkbox.
-1. Click **Save changes**.
+1. Enable password authentication for the web interface, as described in the
+   [sign-in restrictions documentation](../../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled).
+1. Go to your project and select **Settings > General**.
+1. Expand **Merge request (MR) approvals**.
+1. Select the **Require user password for approvals** checkbox.
+1. Select **Save changes**.
 
 ## Security approvals in merge requests **(ULTIMATE)**
 
-Merge request approvals can be configured to require approval from a member
-of your security team when a vulnerability would be introduced by a merge request.
-
-For more information, see
+You can require that a member of your security team approves a merge request if a
+merge request could introduce a vulnerability. To learn more, see
 [Security approvals in merge requests](../../../application_security/index.md#security-approvals-in-merge-requests).
+
+## Related links
+
+- [Instance-level merge request approval settings](../../../admin_area/merge_requests_approvals.md)
+- [Compliance Dashboard](../../../compliance/compliance_dashboard/index.md)
+- [Merge request approvals API](../../../../api/merge_request_approvals.md)

ee/app/views/projects/_merge_request_approvals_settings_form.html.haml

@@ -27,7 +27,7 @@
       = form.check_box(:disable_overriding_approvers_per_merge_request, { class: 'custom-control-input', disabled: !can_modify_approvers })
       = form.label :disable_overriding_approvers_per_merge_request, class: 'custom-control-label' do
         %span= _('Prevent users from modifying MR approval rules in merge requests.')
-        = link_to sprite_icon('question-o'), help_page_path('user/project/merge_requests/approvals/settings', anchor: 'prevent-overriding-default-approvals'), target: '_blank'
+        = link_to sprite_icon('question-o'), help_page_path('user/project/merge_requests/approvals/settings', anchor: 'prevent-overrides-of-default-approvals'), target: '_blank'
 
     .gl-form-checkbox.custom-control.custom-checkbox
       = form.check_box :reset_approvals_on_push, class: 'custom-control-input'
@@ -40,14 +40,14 @@
 
         %span= _('Prevent MR approvals by the author.')
         = link_to sprite_icon('question-o'), help_page_path('user/project/merge_requests/approvals/settings',
-          anchor: 'allowing-merge-request-authors-to-approve-their-own-merge-requests'), target: '_blank'
+          anchor: 'prevent-authors-from-approving-their-own-work'), target: '_blank'
 
     .gl-form-checkbox.custom-control.custom-checkbox
       = form.check_box :merge_requests_disable_committers_approval, { disabled: !can_modify_merge_request_committer_settings, class: 'custom-control-input' }
       = form.label :merge_requests_disable_committers_approval, class: 'custom-control-label' do
         %span= _('Prevent MR approvals from users who make commits to the MR.')
         = link_to sprite_icon('question-o'), help_page_path('user/project/merge_requests/approvals/settings',
-          anchor: 'allowing-merge-request-authors-to-approve-their-own-merge-requests'), target: '_blank'
+          anchor: 'prevent-committers-from-approving-their-own-work'), target: '_blank'
 
     - if password_authentication_enabled_for_web?
       .gl-form-checkbox.custom-control.custom-checkbox
@@ -55,4 +55,4 @@
         = form.label :require_password_to_approve, class: 'custom-control-label' do
           %span= _('Require user password for approvals.')
           = link_to sprite_icon('question-o'), help_page_path('user/project/merge_requests/approvals/settings',
-            anchor: 'require-authentication-when-approving-a-merge-request'), target: '_blank'
+            anchor: 'require-authentication-for-approvals'), target: '_blank'