pull-requests: Helpers for GitHub pull requests

Description Usage Arguments Git/GitHub Authentication For contributors For maintainers Overview of all the functions Examples

Description

The pr_* family of functions is designed to make working with GitHub pull requests (PRs) as painless as possible for both contributors and package maintainers.

To use the pr_* functions, your project must be a Git repo and have one of these GitHub remote configurations:

"Ours" and "fork" are two of several GitHub remote configurations examined in Common remote setups in Happy Git and GitHub for the useR.

The Pull Request Helpers article walks through the process of making a pull request with the pr_* functions.

The pr_* functions also use your Git/GitHub credentials to carry out various remote operations. See below for more.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
pr_init(branch)

pr_resume(branch = NULL)

pr_fetch(number = NULL, target = c("source", "primary"))

pr_push()

pr_pull()

pr_merge_main()

pr_view(number = NULL, target = c("source", "primary"))

pr_pause()

pr_finish(number = NULL, target = c("source", "primary"))

pr_forget()

Arguments

branch

Name of a new or existing local branch. If creating a new branch, note this should usually consist of lower case letters, numbers, and -.

number

Number of PR.

target

Which repo to target? This is only a question in the case of a fork. In a fork, there is some slim chance that you want to consider pull requests against your fork (the primary repo, i.e. origin) instead of those against the source repo (i.e. upstream, which is the default).

Git/GitHub Authentication

Many usethis functions, including those documented here, potentially interact with GitHub in two different ways:

Therefore two types of auth can happen and your credentials must be discoverable. Which credentials do we mean?

Git/GitHub credential management is covered in a dedicated article: Managing Git(Hub) Credentials

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. It is best practice to never make commits to the default branch branch of a fork (usually named main or master), because you do not own it. A pull request should always come from a feature branch. It will be much easier to pull upstream changes from the fork parent if you only allow yourself to work in feature branches. It is also much easier for a maintainer to explore and extend your PR if you create a feature branch.

Work locally, in your branch, making changes to files, and committing your work. Once you're ready to create the PR, run pr_push() to push your local branch to GitHub, and open a webpage that lets you initiate the PR (or draft PR).

To learn more about the process of making a pull request, read the Pull Request Helpers vignette.

If you are lucky, your PR will be perfect, and the maintainer will accept it. You can then run pr_finish() to 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 update your PR.

It's also possible that the maintainer will contribute some code to your PR: to get those changes back onto your computer, run pr_pull(). It can also happen that other changes have occurred in the package since you first created your PR. You might need to merge the default branch (usually named main or master) into your PR branch. Do that by running pr_merge_main(): this makes sure that your PR is compatible with the primary repo's main line of development. Both pr_pull() and pr_merge_main() can result in 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() and select the PR or, if you already know its number, call 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 and remove the remote associated with the contributor's fork.

Overview of all the functions

Examples

1
2
3
4
## Not run: 
pr_fetch(123)

## End(Not run)

usethis documentation built on Feb. 10, 2021, 5:08 p.m.