usethis (version 1.5.0)

pr_init: Helpers for GitHub pull requests

Description

The pr_* family of functions is designed to make working with GitHub PRs as painless as possible for both contributors and package maintainers. They are designed to support the git and GitHub best practices described in http://happygitwithr.com/.

Usage

pr_init(branch)
pr_fetch(number, owner = NULL)
pr_push()
pr_pull()
pr_pull_upstream()
pr_sync()
pr_view()
pr_pause()
pr_finish()

Arguments

branch

branch name. Should usually consist of lower case letters, numbers, and -.

number

Number of PR to fetch.

owner

Name of the owner of the repository that is the target of the pull request. Default of NULL tries to identify the source repo and uses the owner of the upstream remote, if present, or the owner of origin otherwise.

Set up advice

These functions make heavy use of git2r and the GitHub API. You'll need a GitHub personal access token (PAT); see browse_github_token() for help with that. If git2r does not seem to be finding your git credentials, read git_credentials() for troubleshooting advice. The transport protocol (SSH vs HTTPS) is determined from the existing remote URL(s) of the repo.

For contributors

To contribute to a package, first use create_from_github(owner/repo) to fork the source repository, and then check out a local copy. Next use pr_init() to create a branch for your PR (never submit a PR from the master branch). You'll then work locally, making changes to files and checking them into git. Once you're ready to submit, run pr_push() to push your local branch to GitHub, and open a webpage that lets you initiate the PR.

If you are lucky, your PR will be perfect, and the maintainer will accept it. You can then run pr_finish() to close and delete your PR branch. In most cases, however, the maintainer will ask you to make some changes. Make the changes, then run pr_push() to sync back up to GitHub.

It's also possible that the maintainer will contribute some code to your PR: you get that code back to your computer, run pr_pull(). It's also possible that other changes have occurred to the package while you've been working on your PR, and you need to "merge master". Do that by running pr_pull_upstream(): this makes sure that your copy of the package is up-to-date with the maintainer's latest changes. Either of the pull functions may cause merge conflicts, so be prepared to resolve before continuing.

For maintainers

To download a PR locally so that you can experiment with it, run pr_fetch(<pr_number>). If you make changes, run pr_push() to push them back to GitHub. After you have merged the PR, run pr_finish() to delete the local branch.

Other helpful functions

• pr_sync() is a shortcut for pr_pull(), pr_pull_upstream(), and pr_push()

• pr_pause() makes sure you're synced with the PR and then switches back to master.

• pr_view() opens the PR in the browser

Examples

# NOT RUN {
## scenario: current project is a local copy of fork of a repo owned by
## 'tidyverse', not you
pr_fetch(123, owner = "tidyverse")
# }