Pull Request

By now, you should already have submitted two pull requests to the ourpackage repository:

  1. A pull request with your name to the README
  2. A pull request with a method for the print_emoji() function

The first pull request involved a trivial change to the content, but gave you a first exposure to the process. The second pull request gave you another change to practice the process, while introducing some new technical requirements.

This time, you are going to submit a pull request with a fully-formed and documented function.

Deadlines

  • You must open your issue on GitHub by 5 pm on Friday, October 11.
  • You should aim to have me close your issue on GitHub (by merging your pull request) by 5 pm on Friday, November 1.
Important

You may NOT use generative AI tools to write the code for your function. You may use generative AI tools to help with documentation and examples.

How to submit a pull request

  1. Open a New Issue on GitHub with your idea for a function.
    • Tell me what the function is supposed to do
    • Describe any arguments
    • Describe the expected result
    • Show me 2-3 examples of how to use the function
    • Provide a few examples that would verify that the function works as intended
    • DON’T WRITE ANY CODE!!!
  2. I will review your idea and provide feedback. This process will continue until we both have a shared idea for your function.
  3. Sync your fork of the ourpackage repository (see the R package lab)
    • Use usethis::pr_init() to start a new pull request
    • Create a new file R/<your_github_username>.R and write your function. See R Code for help.
    • Document your function
    • Use usethis::pr_push() to open a pull request back to the main repository
  4. When I receive your pull request, I will start providing feedback. I will:
    • provide line-by-line feedback about the style and readability of your code and documentation
    • show you where your function breaks
    • help you think about the output types
    • help you think about how it might fit into a pipeline with other functions
    • help you track down dependencies
    • think about originality and duplication
  5. Update the pull request after incorporating my feedback. This iterative process will continue until the function is acceptable. Expect to go through three or more iterations—your function will almost certainly not be accepted right away.

Pull request criteria

Criteria Improvable OK Good Great
Documentation Code is poorly documented. Code is only partially documented and only works in ideal cases. Code is mostly documented and mostly works as expected. Code is fully documented and always works as expected.
Robustness Errors are easy to generate. Function returns objects of different type than specified. Function can be broken easily but works for sensible inputs. Function is robust to unexpected user input.
Usefulness Function is actually less effective than existing functionality. Function is hard to use because it’s not clear what it is supposed to do, or how it works. Function adds nothing to existing functionality. Function makes only incremental improvements over existing functionality. Purpose of function is clear. Function solves a real problem that is not easily solved using existing functionality.
Sophistication Function requires only basic knowledge of R and lacks ambition. Function uses loops when vectorization would be simpler. Function leverages vectorization but uses loops where iteration would be simpler. Function makes use of vectorization and iteration without using loops.

Background on Code Review

Code review is systematic quality assurance for code (Fagan 2002).

Code reviews should be short! Best practices from a 2006 Cisco study:

  • Lines of code (LOC) under review should be less than 200, not exceeding 400, as anything larger overwhelms reviewers and they stop uncovering defects.
  • The total review time should be less than 60 minutes, not to exceed 90. Defect detection rates plummet after 90 minutes of reviewing.

Pull requests should be small! This dovetails with our recommendation for more frequent, smaller commits

More information is available here:

References

Fagan, Michael. 2002. “Design and Code Inspections to Reduce Errors in Program Development.” In Software Pioneers, 575–607. Springer. https://doi.org/10.1007/978-3-642-59412-0_35.