Week 4: Contributing to Open-Source Packages

---

In the last module, you took a look at the meangirls package by Regina George.

Now let’s help Regina make her package even better.

The usethis package will make this process easy and foolproof. Make sure you have it installed now.

Time Estimates:
     Videos: 30 sec
     Readings: 20 min
     Activities: 40 min
     Check-ins: 5

Extra Resources:

• Pull Requests with usethis
• Why you should contribute to Open Source

Get set up

The first thing you need to do when you want to contribute to someone else’s package is to fork the package.

Recall that a fork is very different from a clone. A clone simply copy-pastes the repository, while a fork retains its link to the original repository.

Now, we could go through the tedious process of forking the repository, then all the steps after that to get it open in your local computer’s RStudio.

Instead, let’s do all these steps in one with usethis. Open up a new RStudio session, load the usethis package, and then run:

create_from_github("Cal-Poly-Advanced-R/meangirls")

A lot of output will print out.

Here’s what this does:

• Forks the meangirls repo, owned by Cal-Poly-Advanced-R on GitHub, into your GitHub account.
• Clones your praise repo into a folder named “meangirls” on your desktop (or similar).
• Does additional git/GitHub setup:
  • Sets your origin remote (the repo you can push directly to) to be your own forked copy of the “meangirls” repo.
  • Sets your upstream remote (the original version that you will later Pull Request) to be the “meangirls” repo owned by Cal-Poly-Advanced-R
  • Sets the master branch to be the original repo’s main branch, so you can pull future edits that Regina makes (“upstream changes”) in the future.
• Opens a new instance of RStudio in the meangirls R project.

Alternative approach

It is also possible to do this steps without create_from_github, if you prefer or if it is not playing nice with your machine.

1. On GitHub, navigate to the package repo and click “Fork”.
2. Using GitHub Desktop (or your preferred method), clone your new forked package to your local machine.
3. Navigate to the folder where you cloned the package, and open the .Rproj.

Check-In 1: Forking setup

Take a screenshot of the console output from create_from_github

OR

Take a screenshot of your RStudio window with the package project open.

Canvas Link     

Make some simple changes

We are now ready to get our hands dirty with this package.

First, build the package.

You can do this by typing Cmd/Ctrl-Shift-B, or by clicking in the “Build” pane:

Open up README.Rmd and knit it.

Scroll to the very bottom. Do you see a problem with the output?

It’s time to fix the give_candygrams() function so that it includes extra messages.

But first, we need to make a branch of our repo, so that when we change the code, it is carefully tracked separately.

In your console, type:

pr_init("fix-candygrams")

This will switch you to a new branch.

Now, we can finally edit the source code.

Fix the code in give_candygrams.R so that the extra messages print out properly. (Hint: This is a small change in only one line of the code!)

Check that the code is fixed by re-building the package, re-knitting the README.Rmd file, and looking at the output at the bottom.

When you are satisfied with your change, commit your changes to Git.

Then run in the console:

pr_push()

This will magically pop up a Pull Request window, like the one from Week 1!

Check-In 2: PR Edits

Complete the Pull Request. Take a screenshot of the “Files Changed” tab of the Pull Request screen.

Unlike Week 1, I will NOT be merging your Pull Requests.

Canvas Link     

Testing packages

Last, let’s check out the unit tests in Regina’s package.

In any package, it’s very important to write automatic tests to check that your functions work the way you hope. As the package gets more complex, you can then keep running your tests to make sure nothing broke along the way.

Run the tests that Regina has written for her package by typing Ctrl/Cmd-Shift-T; or from the drop-down menu in the Build pane:

Oh no! One of the unit tests failed.

In the folder tests/testthat, find the appropriate test file. Figure out how the actual output was different from the expected output.

Check-In 3: More PR Edits

Start a new pull request using pr_init(), as you did above.

Track down the error, and make changes to the function. Keep trying until all tests succeed.

When you are done, finish off the pull request, and take a screenshot.

Canvas Link     

Make a major contribution

When handing out candygrams, Santa has a whole classroom of students to announce.

Required Video: CandyCane Grams

Honestly, this whole movie is required viewing.

It would be tedious to have to call the give_candygrams() function once for each student. Instead, it would be convenient to have a vector of student names and a vector of candygram counts, and run a single function like so:

students <- c("Taylor Zimmerman", "Glen Coco", "Cady Heron", "Gretchen Weiners")
counts <- c(2, 4, 1, 1)


give_many_candygrams(students, counts)

Check-In 4: Contribute a function

1. Write the function give_many_candygrams() into the meangirls package.

2. Do your best to copy the documentation style of the give_candygrams() function. Type Ctrl-Shift-D, or use the Build pane drop-down menu, to automatically write a documentation file for your function.

3. Re-build the package. Then type ?give_many_candygrams in your console.

4. Take a screenshot of the “Help” pane that pops up. It should look like this, except for your new function:

Canvas Link     

Check-In 5: Write a Unit Test

Type in your console:

use_test("give_many_candygrams")

Edit the file that pops up, to create a unit test for your new give_many_candygrams function.

Re-run the tests for the package.

Once all the tests pass, take a screenshot of the Build pane.

It should look like this, but with a total of 7 tests:

Canvas Link