Learning Github Classrooms

10 August 2021

By Allison Horst and the Bren School GitHub Classrooms Learning Group (Tamma Carleton, James Frew, Jamie Montgomery, and Naomi Tague)

Where we started

With our new Master of Environmental Data Science degree program starting at the Bren School (UCSB) in August, a number of faculty and staff in our program wanted to make sure that we were using the most efficient and modern tools to run our classes. Of particular interest was GitHub for some aspects of course management - which we hadn’t used before. After considering a number of options (including the very cool ghclass R package), we settled on getting our feet wet with brand name GitHub Classrooms.

Here are some things we learned in the process.

QUESTION 1: WHAT SERVICE DOES GITHUB CLASSROOMS PROVIDE?

We initially assumed that GitHub Classrooms is a way to manage classes. Things like sharing course materials, emailing students, maybe a forum - the types of things you do in a course created with a Learning Management System.

We quickly learned: that is not what GitHub Classrooms is for. 

GitHub Classrooms is really a tool built for a unique purpose: to easily distribute and access assignments for courses in which GitHub repositories are a logical unit for student assignments. For example, if you have a bunch of students doing data science assignments and their assignment submission exists within a GitHub repo (and you’re increasingly bummed because naming conventions are ignored and now you’re added to a billion student repos as a collaborator so you can view & grade them and it’s kind of a nightmare…), GitHub Classrooms might work really well for your courses.

Two big lessons learned early on that made it easier to think about GitHub Classrooms:

1. The sooner you start thinking about GitHub Classrooms as GitHub Assignments, the less confused you will feel about what it does and doesn’t do.
2. GitHub Classrooms will NOT replace a full course website. It’s an additional thing that helps with assignment distribution, setup and organization if GitHub repositories are a logical unit for students to work in for assignments. Aside: we’ve decided to create our separate course websites with RStudio’s distill package. It’s great for simple websites, especially for people happily working in R.

Note: We focus here on the teaching end of GitHub Classroom. There are also valuable learning opportunities for students, including that “Students can practice with industry standard tools and workflows” (Mongan 2020) while completing their course assignments. 

QUESTION 2: WHAT CONSTITUTES AN ORGANIZATION, A CLASSROOM, AND REPOSITORIES? 

Creating Organizations and Classrooms through https://classroom.github.com/ is pretty point-and-click straightforward (click the Create Classroom button, which will prompt you to add it to an existing Organization or create a new one...so create your new Organization and then add your Classroom to it). What was more confusing for us: What are the units of an Organization, and a Classroom, and repositories within the Organization? 

We knew from minimal research that there is some hierarchy to GitHub Classrooms: a top-level Organization, which contains at least one Classroom, and within the Classroom there are organized repositories where students work. That might sound simple, but we quickly realized we had questions. Like: Should the Organization be an umbrella for a course, with different Classrooms within that Organization each time you teach the course? Or, should the Organization contain a single Classroom for each separate time the course is offered?

Based on what other leaders in data science education recommended (see: Fiksel et al. 2019, Çetinkaya-Rundel et al. 2020), we went with the latter: for each iteration of a course (e.g. DS 100 offered in Spring 2020), we create a separate Organization with a single Classroom in it, specific to that academic term. For example, for DS 100 in Spring 2020, there might be an Organization named ds-100-spring-2020-org, and within it a single Classroom named ds-100-spring-2020.

Comparison of organizational structures for GitHub Classroom. Left: a single umbrella organization containing multiple iterations of a course (not recommended). Right: for each iteration of a course, a single organization is made that contains a single Classroom (recommended).

The Classroom itself just provides a friendly dashboard (or interface, or repo organizer, or whatever) that allows you (the instructor & TAs) to more easily do the things that GitHub Classrooms is functionally great for: automatically creating organized and consistently named assignment repos for multiple students.

Alright. So we settled on one Organization containing one Classroom for every iteration of a course. Cool. Then what are the units of a repo within the organization? Does each student have ONE repo that they work in throughout the class for all assignments? Does each student have a separate repo for every assignment?
The second one. For each assignment, a single repo will be created for each student (if assignments are individual - not tackling team assignments in this post, though GitHub Classrooms does that, too). So, if you have 10 students in a class and there are 3 assignments during the course, there will be a total of 30 repositories created within the Organization, organized nicely in your Classroom interface by Assignment.

Visually, the general structure we’re using (standing on shoulders of DS education giants here, who have already shared this in papers and documentation elsewhere) is something like this:

Schematic of GitHub Classroom assignment structure. For the Classroom, assignments are created and organized within the classroom. For individual assignments, a single repo is created for each student. In this schematic, this would be a Classroom where there are 3 assignments created, and two students have accepted each assignment.

QUESTION 3: OK THEN HOW DO I MAKE THE STUDENTS’ REPOS FOR ALL THE ASSIGNMENTS? (SPOILER: THIS IS GITHUB CLASSROOMS’ TIME TO SHINE)

Sounds daunting, right? Like if you have 95 students, then how do you make and distribute all of their assignment repos when you have 8 assignments throughout the course?

This is where GitHub Classrooms shines. The TL;DR version is:

1. You create the assignment once (setting permissions, choosing a template repo if you want - more on that later, etc.)
2. Once you’re done creating the assignment, a shareable link is created.
3. When you share that link with students on the course roster, they will click on it to accept the assignment.
4. Once a student accepts the assignment, their individual repo that they can work in, make commits to, etc. is automatically created.

What’s really nice about this?

• Setup, distribution and repo creation is beautifully automated
• You personally don’t get invited to a bazillion repositories, but you have access to them
• The naming will be more consistent, because whatever you name the assignment will be the start to the repo name for all students, followed by the students’ GitHub username. For example, if you create an assignment named ‘Assignment 1 Wrangling,’ the repo name created for a student with GitHub username ‘burritowolf’ will be assignment-1-wrangling-burritowolf
• The assignment repos all live in the course Organization (e.g. ds-100-spring-2020-org/assignment-1-wrangling-burritowolf), and through the Classroom interface are nicely organized by Assignment.

That’s it. You make an assignment, share the link, and tell students to accept it - then the repos are created and automatically named for each student assignment. Just like that. And these assignment repos all live within the organization, and are organized within your Classroom by Assignment. Feel free to clap the first time you actually see this work, it’s really pretty awesome.

QUESTION 4: WHAT IF I WANT THEIR ASSIGNMENT REPO TO START WITH SOME MATERIALS IN IT? 

GitHub Classrooms also happily handles this. When creating each assignment, there is an option to use a template repo that contains pre-prepared materials (maybe this is a skeleton script, or instructions, or some data, or whatever you want students’ starting point to be).

If you’re like “What even IS a template repo???” - don’t panic. You seriously just click on the Settings tab of a repo and the first checkbox you see lets you make a repo a template:

Screenshot of checkbox to make a repository a Template repo. The checkbox is under the ‘Settings’ tab for your GitHub repo, immediately below the ‘Repository name’ text box.

All repos that you want to use as assignment starters should be Template repositories.

Where does that template repo live? There are a couple options:

1. If the template is a public template repo, then it can live anywhere. Outside the Classroom Organization is fine. You can point to & use any public template repo.
2. If it’s a private template repo, it needs to be a repository in your Classroom Organization. Which is fine, just know you’ll have to copy your private template repo into your Classroom Organization in order to access it.

QUESTION 5: WHAT IF I WANT TO REUSE MY COURSE MATERIALS YEAR AFTER YEAR (OR TERM AFTER TERM)? 

Fiskel et al. (2019) explain this nicely. If you have some assignments that you want to reuse (or partially reuse / update) year after year, consider creating a separate Organization (not through GitHub Classrooms - just a normal one in your personal GitHub space) that is not specific to the term to store repo templates for course assignments.

Continuing with our DS 100 Spring 2020 example, that organization containing reusable materials might just be called DS-100. Within that Organization, you can create template repositories containing assignments that you plan on reusing, so that they are easily accessed when you create a new Classroom for a future iteration of the course.

The template repos in that Organization can then be used directly for assignment creation (if they’re public), or (if private) duplicated to exist within your specific classroom Organization for use during that term.

CONCLUSION 

We just started our GitHub Classrooms journey, but so far I’d say we’re feeling motivated by how quick it is to create and distribute assignments as GitHub repos for multiple students while maintaining consistent naming conventions and organization. What felt unmanageable at first started feeling much better once we accepted GitHub Classrooms as a tool for Assignment creation and distribution, not a full blown course management option.

It’s been fun testing this as a group so that we can play different roles (teacher, TA, student, etc.) and work on breaking things in test Organizations and Classrooms. We highly recommend making a learning group to try this out instead of flailing lonely on your own.

GO TRY IT OUT, BUT BE WARNED: AVOID THE ORPHANED CLASSROOM VORTEX!

If you are going to make toy Organizations and Classrooms to try this stuff out, when you want to delete them to clean up your space, make sure to delete GitHub Classrooms individually (viewable through Organizations on classroom.github.com, not github.com) before deleting the Organization they live in. You may think (like we did) that when you delete an Organization the Classrooms would be deleted along with it. THEY AREN’T. The Classrooms remain as orphans, but without their parent Organization, you can no longer open the Classrooms, which means you can’t delete them, which means they are just sitting there mocking you forever (or at least until GitHub patches this 500 Error vortex).

Unfortunately, this is an easy mistake to make, because the connection between classrooms and orgs is unidirectional: Classrooms know what org they're in, but Organizations don't know what Classrooms are in them. Specifically: If you go to https://github.com/{org}, you won't see its Classrooms, only its repos, if any. So you might think an Organization is empty, and delete it. GitHub Classrooms are only visible through https://classroom.github.com, so you have to go there to see the Classrooms within an Organization, and delete them there before deleting the Organization that contains them.

So to clean up test Classrooms, go to classroom.github.com to see what Organizations you have with their Classrooms viewable, then delete toy Classrooms you don’t want anymore, then delete the toy Organization they were in. 

Acknowledgements

Thank you to Dr. Nyssa Silbiger and Dr. Grant McDermott for reviewing this post and providing helpful feedback!

Resources

• Using GitHub Classroom by Bill Mongan
• Using GitHub Classroom to Teach Statistics by Fiksel et al. (2019)
• Course management with ghclass by Çetinkaya-Rundel et al. (2020)