Working on assignments with GitHub

Huge thanks to Ben Wiedermann at HMC for sharing the following.

Working on assignments with GitHub

In Math 158, we will use GitHub to access and submit assignments (no Gradescope). Here is the basic structure of how it will work:

1. Get the assignment materials from GitHub classroom.
2. Clone the repository to any machine you are using.
3. Work on the assignment and push back to GitHub.

(4. The grader will then knit your file, if it doesn’t knit, you won’t get credit for it. The grader will grade it and push it back to your GitHub repo. You will find the graded assignment on your own repo.)

Figure 1: image credit: xkcd

The following diagram lays out the process, and the rest of the document provides a more detailed set of instructions.

Figure 2: Flowchart of assignment process.

Installing R + RStudio + Git

Most importantly, please become familiar with Happy Git and GitHub with R. Happy Git with R is an incredibly user friendly resource which includes help for almost every single thing that might happen when getting started.

Happy Git with R is your new best friend.

1. The first step is to install R + RStudio + Git on your machine. (If you are planning to use Pomona’s RStudio server, R + RStudio + Git are all three already installed for you.)

2. Create an account on GitHub (if you already have one, use it!).

3. Introduce everyone: R + RStudio (should happen automatically); yourself to GitHub (see https://happygitwithr.com/); RStudio + GitHub (see https://happygitwithr.com/).

4. Follow the rest of the steps that Jenny Bryan spells out in Happy Git and GitHub with R. Most likely, you only need to work through step 12. Step 15 is detailed below after you have gotten the assignment from GitHub.

Figure 3: The more you read Happy Git with R, the better your life will be.

Get the assignment materials from GitHub Classroom

Each assignment will be provided as a link to GitHub classroom. Click the link. (The link will come to you via an email from Sakai. If you lose the email, or the email goes to your spam folder, check Sakai messages for the assignment link.)

When you use GitHub classroom for the first time, you’ll be asked to authorize GitHub classroom to access your repositories.

The first assignment will be an individual assignment. Some other assignments will be paired or group assignments. To accept an individual assignment, click the “Accept this assignment” button.

For all joint assignments, you will need to create a team before you can start.

• If you are working with a partner, create a team name that contains both of your GitHub ids. (If you are working by yourself, use your GitHub id as your team name.)
• One partner accepts the assignment and creates the team.
• If you are working with a partner, the person who did not create the team and accept the assignment should now click the GitHub classroom link, find the newly created team, and click the Join button.

⚠ You may need to add a description of the assignment (for example “Lab 2”) to team name. This is because GitHub Classroom does seem to make it easy for some people to work in the same group as a previous assignment while other people form new groups.

Figure 4: Accept the assignment to create a different repository for every assignment.

The assignment files will be copied as a private repository that you (and your partner, if applicable) and the course staff have access to.

We will call this version, that lives on your personal GitHub account the GitHub fork.

Clone the assignment (or project) repository on to your own computer(s)

Once your repository has been created, you should clone the code to whatever computer you are working on. Just like a Google Doc, you can work on the files from different machines at different times. Unlike a Google Doc, you’ll have to make sure to open the repo (clone or pull if you’ve aleady cloned) and save the repo (commit + push) more deliberately.

Happy Git with R is your new best friend.

1. Click on the link for the repository.

Figure 5: Clink on the link to your assignment repository to get started.

2. Click the Clone or download button and copy the URL.

Figure 6: Copy the HTTPS URL, and use it to create a new project in RStudio.

3. On the cloning machine (e.g., your own compute or the RStudio server), create a new R project with the URL copied from above. Follow the steps at https://happygitwithr.com/new-github-first.html (section 15.2 New RStudio Project via git clone).

Work on the assignment, push back to GitHub

⚠ Always start your work session with a pull to the computer you are working on, and end your session with a push back to GitHub.

All of the GitHub interaction will take place through the RStudio IDE. The two important steps for getting the assignment back to GitHub are:

pull

If you are working with a colleague or on different machines it is so incredibly important to get in the habit of immediately clicking on pull when you start your work. (If you are working alone on a single machine pull won’t hurt! You’ll just be told that your files are already up to date.)

Figure 7: Always pull before you start. pull-work-save-commit-push

knit your work

Don’t forget to put your name on the assignment. Also, make sure that you knit to pdf. Knit early and often. The more often you knit, the fewer headaches you will have.

Figure 8: Always pull before you start. pull-work-knit-commit-push

commit your work

You don’t need to commit every file, but you do need to commit files that are integral to the analysis (always commite .Rmd, .pdf, data files, images that created the pdf, etc.).

Figure 9: pull-work-knit-commit-push

push your work to GitHub

It is good practice to use meaningful commit messages to help your future self figure out your past work.

Figure 10: pull-work-knit-commit-push

check your work on GitHub

To make sure that the work went through, always check your GitHub repo online to confirm any changes you made.

Figure 11: Check that your changes are correct.

Once assignments are completely graded, you will be able to see your grade and assignment feedback on your own GitHub repo. Grades will also be recorded in Sakai.