course-setup.qmd

---
title: Guide for setting up the course infrastructure
---


_Version 2024_

This guide (hopefully) gives enough instructions for recreating new iterations 
of Stat 406.

# Github Org

## Create a GitHub.com organization

* This is free for faculty with instructor credentials.
  * **Note** make sure you upgrade the organization to a "Github Team."
    If you have registered your instructor credentials with Github,
    you should be able to upgrade for free from the [Github Global Campus](https://education.github.com/globalcampus/teacher) page
    under "Upgrade your academic organizations."
* Allows more comprehensive GitHub actions, PR templates and CODEOWNER behaviour
than the UBC Enterprise version (last I checked)
* Downside is getting students added (though we include R scripts for this)

Once done, go to <https://github.com/watching>. Click the Red Down arrow 
"Unwatch all". Then select this Org. The TAs should do the same.

### Permissions and structure

Settings > Member Privileges

We list only the important ones.

* Base Permissions: No Permission
* Repository creation: None
* Repo forking: None
* Pages creation: None
* Team creation rules: No

Be sure to click save in each area after making changes.

Settings > Actions > General

All repositories: Allow all actions and reusable workflows.

Workflow permissions: Read and write permissions.

### Teams

* 2 teams, one for the TAs and one for the students
* You must then manually add the teams to any repos they should access

I generally give the TAs "Write" permission, and the students "Read" permission
with some exceptions. See the Repos section below.

## Repos

There are typically about 10 repositories. Homeworks and Labs each have 3 with
very similar behaviours. 

Be careful copying directories. All of them have hidden files and folders, e.g.
`.git`. Of particular importance are the `.github` directories which contain PR
templates and GitHub Actions. Also relevant are the `.Rprofile` files which try
to override Student Language settings and avoid unprintible markdown characters.

### Homeworks

#### homework-solutions

This is where most of the work happens. My practice is to create the homework 
solutions first. I edit these (before school starts) until I'm happy. I then 
duplicate the file and remove the answers. The result is 
`hwxx-instructions.Rmd`. The `.gitignore` file should ignore all of the solutions
and commit only the instructions. Then, about 1 week after the deadline, I 
adjust the `.gitignore` and push the solution files.

* Students have Read permission.
* TAs have Write permission.
* The `preamble.tex` file is common to HWs and Labs. It creates a lavender box 
where the solution will go. This makes life easy for the TAs.

#### homework-solutions-private

Exactly the same as `homework-solutions` except that all solutions are available
from the beginning for TA access. To create this, after I'm satisfied with 
`homework-solutions` I copy all files (not the directory) into a new directory,
`git init` then upload to the org. The students never have permission here.

#### homework-template

This is a "template repo" used for creating student specific `homework-studentgh`
repos (using the setup scripts). 

_Very Important_: copy the `hwxx-instructions` files over to a new directory. Do
NOT copy the directory or you'll end up with the solutions visible to the students.

Then rename `hwxx-instructions.Rmd` to `hwxx.Rmd`. Now the students have a 
`.pdf` with instructions, and a template `.Rmd` to work on.

Other important tasks:

* The `.gitignore` is more elaborate in an attempt to avoid students pushing 
junk into these repos.
* The `.github` directory contains 3 files: 
  - `CODEOWNERS` begins as an empty doc which will be populated with the assigned grader later;
  - `pull_request_template.md` is used for all HW submission PRs; 
  - `workflows` contains a GH-action to comment on the PR with the date+time
  when the PR is opened.
* Under Settings > General, select "Template repository". This makes it easier 
to duplicate to the student repos.
* Setup branch protection rules for the `main` branch.
  Create a new ruleset for default branches, and select the following:
  * Require a pull request before merging
  * Require review from Code Owners
  * Block force pushes \
  I recommend adding the @TAs team to the bypass list.

### Labs

The three Labs repos operate exactly as the analogous homework repos.

#### labs-solutions

Do any edits here before class begins.

#### labs-solutions-private

Same as with the homeworks

#### labs-template

Same as with the homeworks

### clicker-solutions

This contains the complete set of clicker questions. 

Answers are hidden in comments on the presentation.

I release them incrementally after each module (copying over from my clicker
deck).

### practice-final

Contains a lengthy practice exam as well as solutions. I usually only post this
during the last week of class.

### open-pr-log

This contains a some GitHub actions to automatically keep track of open PRs for
the TAs.

It's still in testing phase, but should work properly. It will create two 
markdown docs, 1 for labs and 1 for homework. Each shows the assigned TA, the
date the PR was opened, and a link to the PR. If everything is configured
properly, it should run automatically at 3am every night.

* Only the TAs should have access.
* Under Settings > Secrets and Variables > Actions you must add a "Repository 
Secret". This should be a GitHub Personal Access Token created in your account 
(Settings > Developer settings > Tokens (classic)). It needs Repo, Workflow, and
Admin:Org permissions. I set it to expire at the end of the course. I use
it only for this purpose (rather than my other tokens for typical logins).

### `.github` / `.github-private`

These contain README files that give some basic information about the available 
repos and the course.

It's visible Publically, and appears on the Org homepage for all to see. The 
`.github-private` has the same function, but applies only to Org members.

### `bakeoff-bakeoff`

This is for the bonus for HW4. Both TAs and Students have access. I put the 
TA team as CODEOWNERS and protect the `main` branch 
(Settings > Branches > Branch Protection Rules). Here, we "Require approvals" 
and "Require Review from Code Owners".


# R package

This is hosted at <https://github.com/ubc-stat/stat-406-rpackage/>. The main 
purposes are:

1. Documentation of datasets used in class, homework, and labs (if not in other
R packages)
2. Provide a few useful functions.
3. Install all the packages the students need at once, and try to compile LaTeX. 

Package requirements are done manually, unfortunately. Typically, I'll open the
various projects in RStudio and run
`sort(unique(renv::dependencies()$Package))`.  It's not infallible, but works
well.

All necessary packages should go in "Suggests:" in the `DESCRIPTION`. This 
avoids build errors. Note that install via `remotes::install_github()` then 
requires `dependencies = TRUE`.

# Worksheets

These are derived from Matías's Rmd notes from 2018. They haven't been updated
much. 

They are hosted at <https://github.com/ubc-stat/stat-406-worksheets/>.

I tried requiring them one year. The model was to distribute the R code for the
chapters with some random lines removed. Then the students could submit the
completed code for small amounts of credit. It didn't seem to move the needle
much and was hard to grade (autograding would be nice here).

Note that there is a GHaction that automatically renders the book from source and pushes to the
`gh-pages` branch. So local build isn't necessary and derivative files should not be checked in
to version control.


# Course website / lectures

This is hosted at <https://github.com/ubc-stat/stat-406>.

The entire site and all slides are `.qmd` files. It's configured 
following the instructions at
<https://quarto.org/docs/publishing/github-pages.html#publish-action>. This 
means that the site is automatically built and pushed to the `gh-pages` branch 
when the `main` branch is updated. But all `R` computations must be done
_locally_ first (because `execute: freeze: auto`). This avoids the need for
`renv` configuration for the GHaction. So you should render the entire site locally before committing / pushing.

Some notes:

* `_quarto.yml` contains the configuration for the site.
* `_metadata.yml` contains configuration for the slides.
* Installing the course package should install all necessary packages. But some
may be missing.


# `{ghclass}` package

I have my own fork of Colin Rundel's `{ghclass}` package <https://github.com/dajmcdon/ghclass>. This is mainly because
we need to be able to create repos and apply various branch protections and
PR review requirements. I've added a few other things, but nothing major (and
some no longer useful). The version numbering is different from Colin's to
reflect the changes.

Interaction with this package usually involves the course roster, so none of it
is under version control (to avoid possible contamination). 


# Canvas

I use the shell provided by FoS.

Nothing else goes here, but you have to update all the links.

Two or three Canvas Quizzes:

* Quiz 0 collects GitHub accounts, ensures that students read the syllabus. 
Due in Week 1.
* Final Exam is the final
* (optional) Midterm Survey. Sometimes ASDa does this, sometimes I do it.
* I usually record lectures (automatically) using the classroom tech that 
automatically uploads.
* Update the various links on the Homepage.

For the final:

* Set total time on Canvas.
* Set the quiz to begin 5 minutes after the scheduled start time.
* Set the quiz to end 5 minutes _after_ the scheduled end time.
* Use the time limit feature (usually 2 hours).
* Check IDs at the end
* Collect cheatsheets and scratch paper
* Verify that the Canvas exam is submitted.

# Slack

* Set up a free Org. Invite link gets posted to Canvas.
* I add `@students.ubc.ca`, `@ubc.ca`, `@stat.ubc.ca` to the whitelist. 
* I also post the invite on Canvas.
* Create channels before people join. That way you can automatically add 
everyone to channels all at once. I do one for each module, 1 for code/github, 
1 for mechanics. + 1 for the TAs (private)
* Click through all the settings. It's useful to adjust these a bit.
* I find it helpful to block posting in #general. So announcements can go there.
* Once a Module is complete, I would like to archive the relevant channel. The
goal being to avoid posting to the wrong place. However, then the students 
won't know how to find it. A tradeoff I haven't solved.

# Clickers

See <https://lthub.ubc.ca/guides/iclicker-cloud-instructor-guide/>

I only use "Polling" no "Quizzing" and no "Attendance"

* In clicker Settings > Polling > Sharing. Turn off the Sending (to avoid 
students doing it at home)
* No participation points.
* 2 points for correct, 2 for answering.
* Integrations > Set this up with Canvas. Sync the roster. You'll likely have 
to repeat this near the Add/Drop Deadline.
* I only sync the total, since I'll recalibrate later.

# Before Day 1

* Ensure the above are all created.
* Create a `labs-yourusername` from the `labs-template` repo (for the Version 
Control Lecture)
* Double check links on the Canvas site (including the Slack invite)
* Deal with any Canvas announcements
* Add "notes" to the Canvas gradebook. This is a good place to put the 
ghusername: Grades > Gear (settings) > View Options > Notes.

# Populate the Org

Once students start taking the quiz, use the scripts in `gh-class-management` 
to begin

1. Inviting students to GitHub (they must accept the invitation). Announce this!!!
2. Adding those that accept to the "students" team.
  
The responses can be downloaded in a .csv at Quizzes > Lab 0 > Survey Statistics > Student Analysis.

The rest is a bit manual. I do multiple rounds. And sometimes have to filter out
junk responses.