# Open a pull request

Propose merging one branch into another, as a draft or ready for review, and edit its title and description.

A pull request carries reviews, comments, checks and an approval count. Issues and pull requests
share one numbering per repository. The examples use the repository id
`5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60` and the branch add-hint-counter.

## Prerequisites

- Both branches pushed to the repository, and different from each other. Otherwise the API answers
  400 `Source and target branches must differ` or `One of those branches does not exist`.
- Permission for `git:CreatePullRequest`.
- In the Deutsche Cloud Console, also `git:GetRepository` to open the repository's pages (without it the page
  is not found).
- In the Deutsche Cloud Console, **New pull request** is not shown while the repository is archived, is a
  mirror, or is still importing.

## Open it

**Console**
1. In the repository, choose **Pull requests**, then **New pull request**.
2. Under **Branches**, pick the **Source branch** add-hint-counter and the **Target
   branch** (the repository's default branch unless you change it).
3. Enter a **Title** and, optionally, a **Description**.
4. (Optional) Select **Open as draft**.
5. Choose **Create pull request** (or **Create draft pull request**). The pull request's page opens.

**CLI**
```sh
dcloud git pulls create 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 \
  --title "Show clue count" --source-branch add-hint-counter --target-branch main
```

Add `--is-draft` to open it as a draft.

**API**
```http
POST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/pulls
{ "title": "Show clue count", "sourceBranch": "add-hint-counter", "targetBranch": "main", "isDraft": false }
```

## Result

The response carries the merge status (`mergeStatus`):

| `mergeStatus` | Meaning                                 |
| ------------- | --------------------------------------- |
| `mergeable`   | can be merged                           |
| `conflicted`  | has conflicts with the target           |
| `up_to_date`  | nothing to merge                        |
| `unknown`     | cannot be computed: a branch is missing |

Opening a pull request, a draft too, starts the `on: pull_request` workflows and asks the code
owners of the changed files for a review.

## Drafts

A draft cannot be merged, given auto-merge or added to the merge queue until it is marked ready.
It can be reviewed and commented on like an open pull request.

Marking a draft ready, or turning an open pull request back into a draft, needs
`git:UpdatePullRequest`. In the Deutsche Cloud Console, opening the pull request also needs `git:GetRepository`
and `git:GetPullRequest` (without either the page is not found).

**Console**
1. Open the pull request. A draft says **This pull request is still a draft.** in the merge box.
2. Choose **Ready for review**. The pull request is open.

To turn an open pull request back into a draft, choose **Convert to draft** in the merge box.

The buttons are shown only with `git:UpdatePullRequest`, and not in an archived repository or a
mirror, where the API refuses as well (see below). On a pull request whose target branch requires
the merge queue, the merge box and with it these controls is not shown; use the CLI or API there.

**CLI**
```sh
dcloud git pulls ready 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 7
dcloud git pulls convert-to-draft 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 7
```

**API**
```http
POST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/pulls/7/ready
```

```http
POST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/pulls/7/draft
```

The pull request's timeline records who changed it. Marking it ready sends the `ready_for_review`
webhook event and converting it sends `converted_to_draft`; workflows start only if they list that
type under `on.pull_request.types`. Asking for the state it already has answers 200 and changes
nothing.

Refused with 409:

- `The pull request is closed` or `The pull request is merged`.
- `Repository is archived`.
- In a mirror: `This repository is a mirror of …; review and merge its pull requests on ….`

## Pull request states

| State    | Meaning                                          |
| -------- | ------------------------------------------------ |
| `draft`  | a draft; cannot be merged until marked ready     |
| `open`   | ready for review                                 |
| `merged` | merged; the merge commit is on the target branch |
| `closed` | closed without merging; can be reopened          |

**Close pull request** and **Reopen pull request** (`POST …/pulls/{n}/close`, `…/reopen`) need
`git:ClosePullRequest`. Closing a merged or closed one answers 409 `Pull request is already
<state>`; reopening one that is not closed, 409 `Cannot reopen a pull request that is <state>`.
A draft that is closed and reopened is a draft again.

## Edit the title or description

Choose **Edit** next to the title, or **Edit** in the description's **…** menu, while the pull
request is open, a draft or closed (`PATCH /git/api/repositories/{repoId}/pulls/{n}` with `title`
and/or `body`; `git:UpdatePullRequest`). The description is Markdown, and `#12` links to issue or
pull request 12. Edits are refused with 409: on a merged pull request (`A merged pull request is
history`), in an archived repository (`Repository is archived`), and in a mirror, whose pull
requests are the source's.

## Related

- [Review a pull request](review-a-pull-request.md)
- [Merge a pull request](merge-a-pull-request.md)
- [Use a merge queue](use-a-merge-queue.md)
- `git.pulls.create` · `dcloud git pulls create` · `git.pulls.ready` ·
  `dcloud git pulls convert-to-draft`
