Pull Request Flow with usethis

Introduction

usethis has a number of functions that help you move through the pull-request process in a seamless and organized way. This flow chart helps you chose the right function at the right time.

I’ve transcribed the chart above as best I can into a readable list below. The flow chart isn’t a DAG (directed acyclic graph) since work is very much a cyclic activity. In less data science jargon, this means you may have to jump around the list quite a bit.

The usethis functions described are all documented in the usethis Helpers for GitHub pull requests page, and the two functions from the gert package are documented online at the gert Stage and commit changes page.

The pull request flow

• Start
  • Start new work
    • pr_init("new-branch-name")
    • Go to Do Work
  • Resume my work
    • pr_resume("existing-branch")
    • Go to Do Work or Update with…
  • Review someone’s work
    • usethis::pr_fetch(123)
    • Go to Do Work or Update with…
• Do Work
  1. Do work in the branch
     1. Stage files to be committed with gert::git_add()
     2. Commit files to the branch with gert::git_commit()
  2. Is the work ready to be shared?
     • If yes, go to step 3
     • If no, return to step 1
  3. Share local work by pushing to remote branch
     1. usethis::pr_push()
     2. Are you done with this branch?
        • If yes, go to All done?
        • If no, return to step 1
• Update with…
  • the pull request branch
    • pr_pull()
  • the main or upstream branch
    • pr_merge_main()
  • just look at the PR
    • pr_view()
• All done?
  • The PR was merged
    • pr_finish()
  • For now, so keep the local branch
    • pr_pause()
  • Totally and the local branch isn’t needed anymore
    • pr_forget()
  • Return to Start

Download the usethis pr_*() flow chart

• Small JPG Image (190 KB)
• Medium JPG Image (511 KB)
• Large JPG Image (1.36 MB)
• SVG (40 KB)
• SVG, Editable (40 KB)
• Source File .drawio (4 KB)

Pull Request Flow with usethis by Garrick Aden-Buie is licensed under a Creative Commons Attribution 4.0 International License.