ghclass

exclude: true

---
class: title_bg

.title[
ghclass
]

.subtitle[
an R package for managing classes with GitHub
]

.conference[
.name[
JSM 2019 &middot; Denver
]
.bitly[
[bit.ly/JSM2019_ghclass](http://bit.ly/JSM2019_ghclass)
]
]

.author[
.name[
Colin Rundel
]
.school[
Univ of Edinburgh &middot;
Duke Univ
]
]

---

## Reproducible Assignments

**Goals**:

* Teach (enforce) version control and reproducible workflows

* Encourage (enforce) collaboration

* Embrace modern tools and methods

**Organization**:

* Core toolkit: R + RStudio + RMarkdown

* Spend 1 lecture on git / GitHub

* GitHub setup:
  
  * 1 organization / course

* 1 repo / (team | student) / assignment
  
* Randomly assigned teams of 3-4 students / assignment

---

## Setup

1. .sep[ Signup for a GitHub Account

[github.com]() ]

2. .sep[ Get a GitHub personal access token (PAT)

[github.com/settings/tokens](https://github.com/settings/tokens) ]

3. .sep[ Setup git and GitHub access in R

[`usethis` setup vignette](https://usethis.r-lib.org/articles/articles/usethis-setup.html) & [happy git with R](https://happygitwithr.com/) ]

3. .sep[ Signup for GitHub Education

[education.github.com/benefits](https://education.github.com/benefits) ]

4. .sep[ Create a GitHub Organization for your class

[github.com/organizations/new](https://github.com/organizations/new) ]

.center[
Only **Step 5** needs to be repeated for a new class!
]

---

## Introduction to `ghclass`

```r
devtools::install_github("rundel/ghclass")
library(ghclass)
```

Some design principals behind this package:

1. Functions are prefixed with `org`, `repo`, `team`, `github` or `local_repo` to indicate what they operate on.

2. Functions are vectorized over their parameters  (batch related operations).

3. Be verbose about what is happening, report failures but don't halt execution.

4. Most actions are non-destructive (backed by git), the handful of dangerous operations will warn you.

5. Follow the unix design philosophy, work towards simple & composable functions

---

## Org & Roster

We will be using [ghclass-demo](https://github.com/ghclass-demo) as our class organization, hopefully your Org has a slightly more informative name .

.center[
(I find `course#`-`semester` works well, e.g. `Sta323-Sp19`).
]

```r
(roster = readr::read_csv("files/roster.csv"))
```

<PRE class="fansi fansi-output"><CODE>## # A tibble: 6 x 4
## netid email github hw01 
## &lt;chr&gt; &lt;chr&gt; &lt;chr&gt; &lt;chr&gt; 
## 1 za17 anya@school.edu ghclass-anya hw01-team01
## 2 kb34 bruno@school.edu ghclass-bruno hw01-team01
## 3 ac13 celine@school.edu ghclass-celine hw01-team02
## 4 bd88 diego@school.edu ghclass-diego hw01-team02
## 5 se01 elijah@school.edu ghclass-elijah hw01-team03
## 6 df00 francis@school.edu ghclass-francis hw01-team03
</CODE></PRE>

---
background-image: url("imgs/01_github_empty.png")
background-position: center
background-size: contain

---

## Checking your git / GitHub config

```r
github_test_token()
```

<PRE class="fansi fansi-output"><CODE>## ✔ Your github token is functioning correctly.
</CODE></PRE>

```r
usethis::git_sitrep()
```

<PRE class="fansi fansi-output"><CODE>## Git user
## * Name: 'Colin Rundel'
## * Email: 'rundel@gmail.com'
## * Vaccinated: TRUE
## usethis + git2r
## * Default usethis protocol: &lt;unset&gt;
## * git2r supports SSH: TRUE
## * Credentials: '&lt;user-provided git2r credential object with class cred_ssh_key&gt;'
## GitHub
## * Personal access token: '&lt;found in env var&gt;'
## * User: 'rundel'
## * Name: 'Colin Rundel'
## Repo
## * Path: '/Users/rundel/Desktop/Presentations/.git'
## * Local branch -&gt; remote tracking branch: 'master' -&gt; 'origin/master'
## GitHub pull request readiness
## * origin: rundel/Presentations, can push
## * upstream: '&lt;no such remote&gt;'
</CODE></PRE>

---

## Inviting Students

```r
org_invite(org = "ghclass-demo", user = roster$github)
```

<PRE class="fansi fansi-output"><CODE>## ✔ Invited user 'ghclass-anya' to org 'ghclass-demo'.
## ✔ Invited user 'ghclass-bruno' to org 'ghclass-demo'.
## ✔ Invited user 'ghclass-celine' to org 'ghclass-demo'.
## ✔ Invited user 'ghclass-diego' to org 'ghclass-demo'.
## ✔ Invited user 'ghclass-elijah' to org 'ghclass-demo'.
## ✔ Invited user 'ghclass-francis' to org 'ghclass-demo'.
</CODE></PRE>

```r
org_members("ghclass-demo", include_admins = FALSE)
```

```
## character(0)
```

```r
org_pending_members("ghclass-demo")
```

```
## [1] "ghclass-anya"    "ghclass-bruno"   "ghclass-diego"   "ghclass-elijah" 
## [5] "ghclass-francis" "ghclass-celine"
```

---
background-image: url("imgs/02_github_members.png")
background-position: center
background-size: contain

---
background-image: url("imgs/03_github_pending.png")
background-position: center
background-size: contain

---

## A few days later ...

```r
org_members("ghclass-demo", include_admins = FALSE)
```

```
## [1] "ghclass-anya"   "ghclass-bruno"  "ghclass-celine" "ghclass-diego"
```

```r
org_pending_members("ghclass-demo")
```

```
## [1] "ghclass-elijah"  "ghclass-francis"
```

## several emails and a week later  ...

```r
org_members("ghclass-demo", include_admins = FALSE)
```

```
## [1] "ghclass-anya"    "ghclass-bruno"   "ghclass-celine"  "ghclass-diego"  
## [5] "ghclass-elijah"  "ghclass-francis"
```

```r
org_pending_members("ghclass-demo")
```

```
## character(0)
```

---
background-image: url("imgs/04_github_accepted.png")
background-position: center
background-size: contain

---

## Team Assignment

```r
org_create_assignment(org = "ghclass-demo", repo = roster$hw01, user = roster$github, 
                      team = roster$hw01, source_repo = "Sta323-Sp19/hw1")
```

<PRE class="fansi fansi-output"><CODE>## ✔ Created repo 'ghclass-demo/hw01-team01'.
## ✔ Created repo 'ghclass-demo/hw01-team02'.
## ✔ Created repo 'ghclass-demo/hw01-team03'.
## ✔ Created team 'hw01-team01' in org 'ghclass-demo'.
## ✔ Created team 'hw01-team02' in org 'ghclass-demo'.
## ✔ Created team 'hw01-team03' in org 'ghclass-demo'.
## ✔ Added 'ghclass-anya' to team 'hw01-team01'.
## ✔ Added 'ghclass-bruno' to team 'hw01-team01'.
## ✔ Added 'ghclass-celine' to team 'hw01-team02'.
## ✔ Added 'ghclass-diego' to team 'hw01-team02'.
## ✔ Added 'ghclass-elijah' to team 'hw01-team03'.
## ✔ Added 'ghclass-francis' to team 'hw01-team03'.
## ✔ Added team 'hw01-team01' to repo 'ghclass-demo/hw01-team01'.
## ✔ Added team 'hw01-team02' to repo 'ghclass-demo/hw01-team02'.
## ✔ Added team 'hw01-team03' to repo 'ghclass-demo/hw01-team03'.
## ✔ Cloned 'Sta323-Sp19/hw1'.
## ✔ Pushed (mirror) 'hw1' to repo 'ghclass-demo/hw01-team01'.
## ✔ Pushed (mirror) 'hw1' to repo 'ghclass-demo/hw01-team01'.
## ✔ Pushed (mirror) 'hw1' to repo 'ghclass-demo/hw01-team02'.
## ✔ Pushed (mirror) 'hw1' to repo 'ghclass-demo/hw01-team02'.
## ✔ Pushed (mirror) 'hw1' to repo 'ghclass-demo/hw01-team03'.
## ✔ Pushed (mirror) 'hw1' to repo 'ghclass-demo/hw01-team03'.
## ✔ Removed local copy of 'Sta323-Sp19/hw1'
</CODE></PRE>

---
background-image: url("imgs/05_github_hw01_repos.png")
background-position: center
background-size: contain

---

.smaller[

```r
team_create("ghclass-demo", team = roster$hw01)
```

<PRE class="fansi fansi-output"><CODE>## ✔ Created team 'hw01-team01' in org 'ghclass-demo'.
## ✔ Created team 'hw01-team02' in org 'ghclass-demo'.
## ✔ Created team 'hw01-team03' in org 'ghclass-demo'.
</CODE></PRE>

```r
team_invite("ghclass-demo", user = roster$github, team = roster$hw01)
```

<PRE class="fansi fansi-output"><CODE>## ✔ Added 'ghclass-anya' to team 'hw01-team01'.
## ✔ Added 'ghclass-bruno' to team 'hw01-team01'.
## ✔ Added 'ghclass-celine' to team 'hw01-team02'.
## ✔ Added 'ghclass-diego' to team 'hw01-team02'.
## ✔ Added 'ghclass-elijah' to team 'hw01-team03'.
## ✔ Added 'ghclass-francis' to team 'hw01-team03'.
</CODE></PRE>

```r
repo_create("ghclass-demo", name = roster$hw01)
```

```r
repo_add_team(repo = org_repos("ghclass-demo", filter = "hw01-"), 
              team = org_teams("ghclass-demo", filter = "hw01-"))
```

<PRE class="fansi fansi-output"><CODE>## ✔ Added team 'hw01-team01' to repo 'ghclass-demo/hw01-team01'.
## ✔ Added team 'hw01-team02' to repo 'ghclass-demo/hw01-team02'.
## ✔ Added team 'hw01-team03' to repo 'ghclass-demo/hw01-team03'.
</CODE></PRE>

```r
repo_mirror(source_repo = "Sta323-Sp19/hw1", 
            target_repo = org_repos("ghclass-demo", filter = "hw01-"))
```

<PRE class="fansi fansi-output"><CODE>## ✔ Cloned 'Sta323-Sp19/hw1'.
## ✔ Pushed (mirror) 'hw1' to repo 'ghclass-demo/hw01-team01'.
## ✔ Pushed (mirror) 'hw1' to repo 'ghclass-demo/hw01-team02'.
## ✔ Pushed (mirror) 'hw1' to repo 'ghclass-demo/hw01-team03'.
## ✔ Removed local copy of 'Sta323-Sp19/hw1'
</CODE></PRE>
]

---

## Individual Assignment

```r
org_create_assignment(org = "ghclass-demo", repo = paste0("mid1-", roster$github),
                      user = roster$github, source_repo = "Sta323-Sp19/midterm1")
```

<PRE class="fansi fansi-output"><CODE>## ✔ Created repo 'ghclass-demo/mid1-ghclass-anya'.
## ✔ Created repo 'ghclass-demo/mid1-ghclass-bruno'.
## ✔ Created repo 'ghclass-demo/mid1-ghclass-celine'.
## ✔ Created repo 'ghclass-demo/mid1-ghclass-diego'.
## ✔ Created repo 'ghclass-demo/mid1-ghclass-elijah'.
## ✔ Created repo 'ghclass-demo/mid1-ghclass-francis'.
## ✔ Added user 'ghclass-anya' to repo 'ghclass-demo/mid1-ghclass-anya'.
## ✔ Added user 'ghclass-bruno' to repo 'ghclass-demo/mid1-ghclass-bruno'.
## ✔ Added user 'ghclass-celine' to repo 'ghclass-demo/mid1-ghclass-celine'.
## ✔ Added user 'ghclass-diego' to repo 'ghclass-demo/mid1-ghclass-diego'.
## ✔ Added user 'ghclass-elijah' to repo 'ghclass-demo/mid1-ghclass-elijah'.
## ✔ Added user 'ghclass-francis' to repo 'ghclass-demo/mid1-ghclass-francis'.
## ✔ Cloned 'Sta323-Sp19/midterm1'.
## ✔ Pushed (mirror) 'midterm1' to repo 'ghclass-demo/mid1-ghclass-anya'.
## ✔ Pushed (mirror) 'midterm1' to repo 'ghclass-demo/mid1-ghclass-bruno'.
## ✔ Pushed (mirror) 'midterm1' to repo 'ghclass-demo/mid1-ghclass-celine'.
## ✔ Pushed (mirror) 'midterm1' to repo 'ghclass-demo/mid1-ghclass-diego'.
## ✔ Pushed (mirror) 'midterm1' to repo 'ghclass-demo/mid1-ghclass-elijah'.
## ✔ Pushed (mirror) 'midterm1' to repo 'ghclass-demo/mid1-ghclass-francis'.
## ✔ Removed local copy of 'Sta323-Sp19/midterm1'
</CODE></PRE>

---
background-image: url("imgs/06_github_mid1_repos.png")
background-position: center
background-size: contain

---

## What about GitHub Classroom?

---

## Making Changes

```r
repo_add_file(repo = org_repos("ghclass-demo", "hw01-"),
              file = "files/fizzbuzz.png")
```

<PRE class="fansi fansi-output"><CODE>## ✖ Failed to add file 'fizzbuzz.png' to repo 'ghclass-demo/hw01-team01': already exists.
## If you want to force-add this file, re-run the command with `overwrite = TRUE`.
## ✖ Failed to add file 'fizzbuzz.png' to repo 'ghclass-demo/hw01-team02': already exists.
## If you want to force-add this file, re-run the command with `overwrite = TRUE`.
## ✖ Failed to add file 'fizzbuzz.png' to repo 'ghclass-demo/hw01-team03': already exists.
## If you want to force-add this file, re-run the command with `overwrite = TRUE`.
</CODE></PRE>

```r
repo_add_file(repo = org_repos("ghclass-demo", "hw01-"),
              file = "files/fizzbuzz.png", overwrite = TRUE)
```

<PRE class="fansi fansi-output"><CODE>## ✔ Added file 'fizzbuzz.png' to repo 'ghclass-demo/hw01-team01'.
## ✔ Added file 'fizzbuzz.png' to repo 'ghclass-demo/hw01-team02'.
## ✔ Added file 'fizzbuzz.png' to repo 'ghclass-demo/hw01-team03'.
</CODE></PRE>

---
background-image: url("imgs/10_github_readme1.png")
background-position: center
background-size: contain

---

## Modify a file

```r
repo_modify_file(repo = org_repos("ghclass-demo", "hw01-"), file = "README.md",
                 pattern = "on Thursday 1/24/2019.", content = "on Wednesday 10/07/2019.")
```

<PRE class="fansi fansi-output"><CODE>## ✔ Modified file 'ghclass-demo/hw01-team01/README.md'.
## ✔ Modified file 'ghclass-demo/hw01-team02/README.md'.
## ✔ Modified file 'ghclass-demo/hw01-team03/README.md'.
</CODE></PRE>

---

## Collect student work

```r
local_repo_clone(repo = org_repos("ghclass-demo", "mid1-"), local_path = "mid1")
```

<PRE class="fansi fansi-output"><CODE>## ✔ Cloned 'ghclass-demo/mid1-ghclass-anya'.
## ✔ Cloned 'ghclass-demo/mid1-ghclass-bruno'.
## ✔ Cloned 'ghclass-demo/mid1-ghclass-celine'.
## ✔ Cloned 'ghclass-demo/mid1-ghclass-diego'.
## ✔ Cloned 'ghclass-demo/mid1-ghclass-elijah'.
## ✔ Cloned 'ghclass-demo/mid1-ghclass-francis'.
</CODE></PRE>

---

## Organize student work

```r
local_repo_rename(repo_dir = "mid1", pattern = roster$github, 
                  replacement = paste0(roster$netid, "-(\\1)"))
```

<PRE class="fansi fansi-output"><CODE>## ✔ Renaming 'mid1/mid1-ghclass-anya' to 'mid1/mid1-za17-(ghclass-anya)'.
## ✔ Renaming 'mid1/mid1-ghclass-bruno' to 'mid1/mid1-kb34-(ghclass-bruno)'.
## ✔ Renaming 'mid1/mid1-ghclass-celine' to 'mid1/mid1-ac13-(ghclass-celine)'.
## ✔ Renaming 'mid1/mid1-ghclass-diego' to 'mid1/mid1-bd88-(ghclass-diego)'.
## ✔ Renaming 'mid1/mid1-ghclass-elijah' to 'mid1/mid1-se01-(ghclass-elijah)'.
## ✔ Renaming 'mid1/mid1-ghclass-francis' to 'mid1/mid1-df00-(ghclass-francis)'.
</CODE></PRE>

---

## Feedback?

```r
repo_style("ghclass-demo/hw01-team01", files = "*.Rmd", draft = TRUE)
```

<PRE class="fansi fansi-output"><CODE>## ✔ Created branch 'styler' from 'ghclass-demo/hw01-team01'.
## ✔ Cloned 'ghclass-demo/hw01-team01@styler'.
## ✔ Created pull request for 'ghclass-demo/hw01-team01 (master &lt;= styler)'.
</CODE></PRE>

---
background-image: url("imgs/16_github_diff.png")
background-position: center
background-size: contain

---

## Future Work

* We will be submitting to CRAN in the next month

* Active summer project adding functionality for peer review by Mine Cetinkaya-Rundel and Therese Anders

* Support for GitHub actions for automated feedback ([rundel/wercker](https://github.com/rundel/wercker) replacement)

* Support more workflows, if you use a GitHub based workflow for teaching that was not reflected here please get in touch.

---

# Thank you!

.middle[ .center[

<div style="width: 98%">
<table class="contact" style="text-align: left; font-size: 120%; margin-left:auto; margin-right:auto; width:50%;">
<tbody>
<tr>
 <td style="vertical-align: middle;"> </td>
 <td> 
 <a href="http://bit.ly/User2019_ghclass">bit.ly/JSM2019_ghclass</a>
 </td>
</tr>
<tr><td> </td></tr>
<tr>
 <td style="vertical-align: middle;"> </td>
 <td> 
 <a href="https://github.com/rundel/ghclass">rundel/ghclass</a> 
 </td>
</tr>
<tr><td> </td></tr>
<tr>
 <td style="vertical-align: middle;"> </td>
 <td> 
 <a href="https://rundel.github.io/ghclass">rundel.github.io/ghclass</a>
 </td>
</tr>
<tr><td> </td></tr>
<tr>
 <td style="vertical-align: middle;"> </td>
 <td> 
 <a href="https://github.com/rundel">github.com/rundel</a>
 </td>
</tr>
<tr><td> </td></tr>
<tr>
 <td style="vertical-align: middle;"> </td>
 <td> 
 <a href="mailto:rundel@gmail.com">rundel@gmail.com</a>
 </td>
</tr>
<tr><td> </td></tr>
<tr>
 <td style="vertical-align: middle;"> </td>
 <td> 
 <a href="https://twitter.com/rundel">@rundel</a>
 </td>
</tr>
</tbody>
</table>
</div>
] ]