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