# Review a pull request

Approve, request changes or comment, on the pull request or on a line of the diff, and suggest changes the author can commit.

A review is `approved`, `changes_requested` or `commented`. Comments can be on the pull request or
on a line of the diff, and threads can be resolved. The examples use the repository id
`5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60` and pull request 7.

## Prerequisites

- Permission for `git:ReviewPullRequest` to review, comment and request reviewers.
- To commit a suggestion, `git:PushRepository`.
- In the Deutsche Cloud Console, also `git:GetRepository` and `git:GetPullRequest` to open the pull request
  (without either the page is not found).
- The repository is not a mirror. A review on a mirror is refused with 409
  `This repository is a mirror of <source>; review and merge its pull requests on <source>.`

An approval from the pull request's author never counts toward the required approvals, and only
each reviewer's latest approval or change request counts.

## Submit a review

**Console**
1. Open the pull request. The review form is on the **Conversation** and **Files** tabs of an open
   or draft pull request.
2. Under **Finish your review**, select **Approve**, **Request changes** or **Comment**.
3. (Optional) Enter a summary of the review.
4. Choose **Submit review**. The review appears in the timeline.

**CLI**
```sh
dcloud git pulls review 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 7 \
  --state approved --body "Looks good"
```

**API**
```http
POST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/pulls/7/reviews
{ "state": "approved", "body": "Looks good" }
```

A comment on a line of the diff takes `filePath`, `line` and `side` (`old` or `new`) together, with
`dcloud git pulls comment`; one or two of them alone is refused. Reviewers are requested with
`dcloud git pulls add-reviewer`. A thread is resolved with
`POST …/pulls/{n}/comments/{commentId}/resolve` and `{ "resolved": true }`
(`dcloud git pulls resolve-comment`).

## Suggest a change

On a line of the changed file, **Suggest a change** puts the line in a `suggestion` block to edit:

```suggestion
const total = Math.round(sum * 100) / 100;
```

Anyone who may push (`git:PushRepository`) sees **Commit suggestion**: the line is replaced on the
pull request's branch as their commit, through the same branch protection as a push, and the
thread is resolved (`POST …/pulls/{n}/comments/{commentId}/apply-suggestion`). An empty block
deletes the line, and a block of several lines replaces the one line it is on with them. A
suggestion made before the branch moved is refused with 409
`Outdated: the branch has moved since this suggestion was made`; one on a line that no longer
exists with 422 `The line no longer exists`. Only a comment on the new side of the diff can be
committed.

## The timeline

Issues and pull requests share one layout: the thread on the left, and **Reviewers** (pull
requests), **Assignees** and **Labels** on the right. Between the comments the thread shows who
added or removed a label, assigned someone, closed, reopened or renamed it, and on a pull request
who requested a review (or that CODEOWNERS did), enabled auto-merge, merged it, and its commits.
A pull request's assignees are set with `PUT …/pulls/{n}/assignees` and its labels with
`PUT …/pulls/{n}/labels` (both `git:UpdateIssue`).

## Related

- [Merge a pull request](merge-a-pull-request.md)
- [Require review from code owners](require-code-owner-review.md)
- `git.pulls.review` · `dcloud git pulls review`
