Merge branch '324948-aqualls-approvals-index-page' into 'master'

Complete CTRT rewrite of approvals page

See merge request gitlab-org/gitlab!60542

doc/development/code_review.md

@@ -39,7 +39,7 @@ or more [maintainers](https://about.gitlab.com/handbook/engineering/workflow/cod
 
 For approvals, we use the approval functionality found in the merge request
 widget. For reviewers, we use the [reviewer functionality](../user/project/merge_requests/getting_started.md#reviewer) in the sidebar.
-Reviewers can add their approval by [approving additionally](../user/project/merge_requests/approvals/index.md#adding-or-removing-an-approval).
+Reviewers can add their approval by [approving additionally](../user/project/merge_requests/approvals/index.md#approve-a-merge-request).
 
 Getting your merge request **merged** also requires a maintainer. If it requires
 more than one approval, the last maintainer to review and approve merges it.

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

@@ -6,111 +6,124 @@ type: reference, concepts
 disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html'
 ---
 
-# Merge Request Approvals **(FREE)**
+# Merge request approvals **(FREE)**
 
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/580) in GitLab Enterprise Edition 7.2. Available in GitLab Free and higher tiers.
-> - Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/10685) in 12.0.
+> Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/10685) in 12.0.
 
-Code review is an essential practice of every successful project. Approving a
-merge request is an important part of the review
-process, as it clearly communicates the ability to merge the change.
-A [merge request approvals API](../../../../api/merge_request_approvals.md) is also available.
+Successful projects depend on code reviews. Merge request approvals clearly communicate
+someone's ability to merge proposed changes. Approvals [are optional](#optional-approvals)
+in GitLab Free, but you can require them for your project in higher tiers.
 
-## Optional Approvals
+Merge request approvals are configured at the project level. Administrator users
+of self-managed GitLab installations can also configure
+[instance-level approval rules](../../../admin_area/merge_requests_approvals.md)
+that cannot be overridden on a project-level basis.
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27426) in GitLab 13.2.
+With [merge request approval rules](rules.md), you can set the minimum number of
+required approvals before work can merge into your project. You can also extend these
+rules to define what types of users can approve work. Some examples of rules you can create include:
 
-Any user with Developer or greater [permissions](../../../permissions.md) can approve a merge request in GitLab Free and higher tiers.
-This provides a consistent mechanism for reviewers to approve merge requests, and ensures
-maintainers know a change is ready to merge. Approvals in Free are optional, and do
-not prevent a merge request from being merged when there is no approval.
+- 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
+  to the repository.
+- Users with specific permissions can be allowed or denied the ability
+  to override approval rules on a specific merge request.
 
-## External approvals **(ULTIMATE)**
+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:
 
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab Ultimate 13.10.
-> - It's [deployed behind a feature flag](../../../feature_flags.md), disabled by default.
-> - It's disabled on GitLab.com.
-> - It's not recommended for production use.
-> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](../../../../api/merge_request_approvals.md#enable-or-disable-external-project-level-mr-approvals). **(ULTIMATE SELF)**
+- 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.
 
-WARNING:
-This feature might not be available to you. Check the **version history** note above for details.
+You can configure your merge request approval rules and settings through the GitLab
+user interface or [with the API](../../../../api/merge_request_approvals.md).
 
-When you create an external approval rule, the following merge request actions sends information
-about a merge request to a third party service:
+## Approve a merge request
 
-- Create
-- Change
-- Close
+When an [eligible approver](rules.md#eligible-approvers) visits an open merge request,
+GitLab displays one of these buttons after the body of the merge request:
 
-This action enables use-cases such as:
+- **Approve**: The merge request doesn't yet have the required number of approvals.
+- **Approve additionally**: The merge request has the required number of approvals.
+- **Revoke approval**: The user viewing the merge request has already approved
+  the merge request.
 
-- Integration with 3rd party workflow tools, such as [ServiceNow](https://www.servicenow.co.uk/).
-- Integration with custom tools designed to approve merge requests from outside of GitLab.
+Eligible approvers can also use the `/approve`
+[quick action](../../../project/quick_actions.md) when adding a comment to
+a merge request.
 
-You can find more information about use-cases, development timelines and the feature discovery in
-the [External API approval rules epic](https://gitlab.com/groups/gitlab-org/-/epics/3869).
+After a merge request receives the [number and type of approvals](rules.md) you configure, it can merge
+unless it's blocked for another reason. Merge requests can be blocked by other problems,
+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).
 
-The intention for this feature is to allow those 3rd party tools to approve a merge request similarly to how users current do.
+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)
+in your project's settings.
 
-NOTE:
-The lack of an external approval does not block the merging of a merge request.
+If you enable [approval rule overrides](settings.md#prevent-overriding-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#scoped-to-protected-branch)
+of the rule.
 
-You can modify external approval rules through the [REST API](../../../../api/merge_request_approvals.md#external-project-level-mr-approvals).
+## Optional approvals
 
-## Required Approvals **(PREMIUM)**
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27426) in GitLab 13.2.
 
-> - [Introduced](https://about.gitlab.com/releases/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only) in GitLab Enterprise Edition 7.12.
-> - Moved to GitLab Premium in 13.9.
+GitLab allows all users with Developer or greater [permissions](../../../permissions.md)
+to approve merge requests. Approvals in GitLab Free are optional, and don't prevent
+a merge request from merging without approval.
 
-Required approvals enable enforced code review by requiring specified people
-to approve a merge request before it can be merged.
+## Required approvals **(PREMIUM)**
 
-Required approvals enable multiple use cases:
+> Moved to [GitLab Premium](https://about.gitlab.com/pricing/) in 13.9.
 
-- Enforcing review of all code that gets merged into a repository.
-- Specifying reviewers for a given proposed code change, as well as a minimum number
-  of reviewers, through [Approval rules](rules.md).
-- Specifying categories of reviewers, such as backend, frontend, quality assurance,
-  database, and so on, for all proposed code changes.
-- Designating [Code Owners as eligible approvers](rules.md#code-owners-as-eligible-approvers),
-  determined by the files changed in a merge request.
-- [Requiring approval from a security team](../../../application_security/index.md#security-approvals-in-merge-requests)
-  before merging code that could introduce a vulnerability.**(ULTIMATE)**
+Required approvals enforce code reviews by the number and type of users you specify.
+Without the approvals, the work cannot merge. Required approvals enable multiple use cases:
 
-### Adding or removing an approval
-
-When an [eligible approver](rules.md#eligible-approvers) visits an open merge request,
-one of the following is possible:
+- Enforce review of all code that gets merged into a repository.
+- Specify reviewers for a given proposed code change, and a minimum number
+  of reviewers, through [Approval rules](rules.md).
+- Specify categories of reviewers, such as backend, frontend, quality assurance, or
+  database, for all proposed code changes.
+- Use the [code owners of changed files](rules.md#code-owners-as-eligible-approvers),
+  to determine who should review the work.
+- [Require approval from a security team](../../../application_security/index.md#security-approvals-in-merge-requests)
+  before merging code that could introduce a vulnerability. **(ULTIMATE)**
 
-- If the required number of approvals has _not_ been yet met, they can approve
-  it by clicking the displayed **Approve** button.
+## Notify external services **(ULTIMATE)**
 
-  ![Approve](img/approve.png)
+> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab Ultimate 13.10.
+> - [Deployed behind a feature flag](../../../feature_flags.md), disabled by default.
+> - Disabled on GitLab.com.
+> - Not recommended for production use.
+> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](../../../../api/merge_request_approvals.md#enable-or-disable-external-project-level-mr-approvals). **(ULTIMATE SELF)**
 
-- If the required number of approvals has already been met, they can still
-  approve it by clicking the displayed **Approve additionally** button.
+WARNING:
+This feature might not be available to you. Check the **version history** note above for details.
 
-  ![Add approval](img/approve_additionally.png)
+You can create an external approval rule to integrate approvals with third-party tools.
+When users create, change, or close merge requests, GitLab sends a notification.
+The users of the third-party tools can then approve merge requests from outside of GitLab.
 
-- **They have already approved this merge request**: They can remove their approval.
+With this integration, you can integrate with third-party workflow tools, like
+[ServiceNow](https://www.servicenow.co.uk/), or the custom tool of your choice.
+You can modify your external approval rules
+[by using the REST API](../../../../api/merge_request_approvals.md#external-project-level-mr-approvals).
 
-  ![Remove approval](img/remove_approval.png)
+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,
-changes to default approval rules will **not** be applied to existing
-merge requests, except for changes to the [target branch](rules.md#scoped-to-protected-branch)
-of the rule.
+To learn more about use cases, feature discovery, and development timelines,
+see the [External API approval rules epic](https://gitlab.com/groups/gitlab-org/-/epics/3869).
 
-NOTE:
-The merge request author is not allowed to approve their own merge request if
-[**Prevent author approval**](settings.md#allowing-merge-request-authors-to-approve-their-own-merge-requests)
-is enabled in the project settings.
+## Related links
 
-After the approval rules have been met, the merge request can be merged if there is nothing
-else blocking it. Note that the merge request could still be blocked by other conditions,
-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).
+- [Merge request approvals API](../../../../api/merge_request_approvals.md)
+- [Instance-level approval rules](../../../admin_area/merge_requests_approvals.md) for self-managed installations
 
 <!-- ## Troubleshooting