ghclass

exclude: true

---
class: title_bg

.title[
ghclass
]

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

.conference[
.name[
UseR!2019 &middot; Toulouse
]
.bitly[
[bit.ly/User2019_ghclass](http://bit.ly/User2019_ghclass)
]
]

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

---
background-image: url("imgs/workflow.001.jpeg")
background-position: center
background-size: contain

---
background-image: url("imgs/workflow.002.jpeg")
background-position: center
background-size: contain

---
background-image: url("imgs/workflow.003.jpeg")
background-position: center
background-size: contain

---
background-image: url("imgs/github_org.jpeg")
background-position: center
background-size: contain

---

## Setup

1. Signup for a GitHub Account - [github.com]()

2. Setup git and get a GitHub personal access token (PAT) - [github.com/settings/tokens](https://github.com/settings/tokens)
  - Need help? Read [usethis setup vignette](https://usethis.r-lib.org/articles/articles/usethis-setup.html) or [happy git with R](https://happygitwithr.com/)

3. Signup for the GitHub Education Discount - [education.github.com/benefits](https://education.github.com/benefits)

4. Create a GitHub Organization for your class - [github.com/organizations/new](https://github.com/organizations/new)

.center[
Only step 4 needs to be repeated for a new class!
]

---

## Introduction to `ghclass`

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

Some design principals behind this package:

1. All of the package's functions are prefixed with either `org`, `repo`, `team`, `github` or `local_repo` to indicate what they operate on.

2. Most functions are vectorized over their parameters, to allow related operations to be grouped.

3. All messaging is built on `usethis::ui_`* functions, as such you can make it shutup with `options(usethis.quiet = TRUE)`.

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

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

---

## Org & Roster

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

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

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

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

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

---

## Checking your git config

```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;usethis + git2r default behaviour&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>

---

## Checking your git config -  `ghclass`

```r
github_test_token()
```

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

```r
github_test_token("bad token")
```

<PRE class="fansi fansi-output"><CODE>## ✖ Your github token failed to authenticate.
## [Error: GitHub API error (401): 401 Unauthorized]
</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'.
## ℹ User 'ghclass-elijah' is already a pending member of org 'ghclass-demo'.
## ℹ User 'ghclass-francis' is already a pending member of 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-elijah"  "ghclass-francis"
## [5] "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

---

## Setup Teams

```r
roster
```

```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-diego' to team 'hw01-team01'.
## ✔ Added 'ghclass-bruno' to team 'hw01-team02'.
## ✔ Added 'ghclass-elijah' to team 'hw01-team02'.
## ✔ Added 'ghclass-celine' to team 'hw01-team03'.
## ✔ Added 'ghclass-francis' to team 'hw01-team03'.
</CODE></PRE>
---
background-image: url("imgs/05_github_org_teams.png")
background-position: center
background-size: contain

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

---

## Setup Repos

```r
roster$hw01
```

```
## [1] "hw01-team01" "hw01-team02" "hw01-team03" "hw01-team01" "hw01-team02"
## [6] "hw01-team03"
```

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

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

```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>

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

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

---

## Provide Template Code

```r
(repos = org_repos("ghclass-demo", filter = "hw01-"))
```

```
## [1] "ghclass-demo/hw01-team01" "ghclass-demo/hw01-team02"
## [3] "ghclass-demo/hw01-team03"
```

```r
repo_mirror(source_repo = "Sta323-Sp19/hw1", 
            target_repo = repos)
```

<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>

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

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

---

## Save some steps

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

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

---

## Individual assignments (e.g. exams)

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

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

---

## Making Changes

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

<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>

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

---

## 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>

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

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

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

---

## Collect student work

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

<PRE class="fansi fansi-output"><CODE>## ✔ Cloned 'ghclass-demo/hw01-team01'.
## ✔ Cloned 'ghclass-demo/hw01-team02'.
## ✔ Cloned 'ghclass-demo/hw01-team03'.
</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/13_github_pull_req.png")
background-position: center
background-size: contain

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

---

## Putting it all together

This is an example from my Organization folder for my Statistical Computing course last Spring:

```r
library(ghclass)
library(dplyr)

df = readr::read_csv("hw2_teams.csv")

team_create("Sta323-Sp19", team = df$team)
team_invite("Sta323-Sp19", df$github, df$team)

repo_create("Sta323-Sp19", df$team)
repo_add_team(org_repos("Sta323-Sp19","hw2-"), org_teams("Sta323-Sp19","hw2-"))

mirror_repo("Sta323-Sp19/hw2", org_repos("Sta323-Sp19","hw2-"))

wercker_add(repo = org_repos("Sta323-Sp19","hw2-"), wercker_org = "Sta323-Sp19")

branch_create(
  repo = paste0("Sta323-Sp19/", df$team),
  cur_branch = "master",
  new_branch = df$github
)
```

---

## 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 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="https://github.com/rundel/ghclass">rundel/ghclass</a>
 </td>
</tr>
<tr><td> </td></tr>
<tr>
 <td style="vertical-align: middle;"> </td>
 <td> 
 <a href="http://bit.ly/User2019_ghclass">bit.ly/User2019_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>
] ]