# ssb-pull-requests

Pull requests for [ssb-git-repo][]s, inheriting from [ssb-issues][].

## API

```
var Pulls = require('ssb-pull-requests')
var pulls = Pulls.init(sbot)
```

#### get: async

Get a pull request by its id

```js
pulls.get(id, cb)
```

→
```js
{
  id: Ref,
  created_at: timestamp,
  headRepo: Ref,
  headBranch: string,
  baseRepo: Ref,
  baseBranch: string,
  title: string?,
  text: string?,
  open: boolean,
  mergeable: boolean?
}
```

- `mergeable`: whether the pull request can be automatically merged (`true`),
  or not (`false`), or it is unknown (`null`)

#### getRevs: async

Get the base and head revisions for a pull request. These revs may be used to
calculate what changes are in a pull request when the revs of the branches may
have changed if the pull request was merged or the upstream diverged.

```js
pulls.get(prId, cb)
```

→
```js
{
  head: string,
  base: string
}
```

- `base`: commit ID of the branch to request changes pulled into
- `head`: commit ID of the branch to pull from


#### list: source

Get a stream of pull requests

```js
issues.list({ repo:, open:, author:, live:, gt:, gte:, lt:, lte:, reverse: })
```

- `repo` (Ref): filter by base git-ssb repo
- `open` (boolean): filter by open/closed status
- `author` (FeedRef): get only pull requests created by the given feed
- `live` (boolean, default: `false`): Keep the stream open and emit new messages as they are received.
- `gt` (greater than), `gte` (greater than or equal): maximum `[timestamp, id]`
- `lt` (less than), `lte` (less than or equal): minimum `[timestamp, id]`
- `reverse` (boolean, default: `false`): reverse the order of results

→
```js
{
  id: Ref,
  created_at: timestamp,
  repo: Ref,
  branch: string,
  head_repo: Ref,
  head_branch: string,
  title: string?,
  text: string?,
  open: boolean,
  mergeable: boolean?,
}
```

- `mergeable`: whether the pull request can be automatically merged

#### deinit: async

Deinit `pulls`. Closes all live streams.

```js
pulls.deinit(cb)
```

## Schemas

```js
var prSchemas = Pulls.schemas
```

#### `prSchemas.new(baseRepo, baseBranch, headRepo, headBranch[, title], text)`

Create a pull request. A pull request is a request to pull from a branch of one
git-ssb repo (head), to a branch on another git-ssb repo (base).

- `baseRepo` (Ref): repo to request changes pulled into
- `baseBranch` (string): branch of the repo to request changes pulled into
- `headRepo` (Ref): repo where the changes are implemented
- `headBranch` (string): branch of the repo to pull from
- `title` (string): title of the pull request (deprecated)
- `text` (string): text describing the pull request

→

```js
{
  type: 'pull-request',
  project: Ref,
  repo: Ref,
  branch: string,
  base_repo: Ref,
  base_branch: string,
  title: string?,
  text: string?
}
```

[git-ssb]: %n92DiQh7ietE+R+X/I403LQoyf2DtR3WQfCkDKlheQU=.sha256
[ssb-git-repo]: %xChSOex77EjNh+oS8LPLdq+4nK1gylButbAgjS1IINs=.sha256
[ssb-issues]: %k2hR1aGh735Y7bgIeoPepMGbagO8YBBau1cUa6wVJGU=.sha256

## License

Copyright (c) 2016 Charles Lehner

Usage of the works is permitted provided that this instrument is
retained with the works, so that any entity that uses the works is
notified of this instrument.

DISCLAIMER: THE WORKS ARE WITHOUT WARRANTY.