How to use pull requests in the classroom

So you’ve given an assignment to your students in GitHub Classroom, either individually or in groups. But have you given a thought to how your students will work in a way that you can give them useful and instructive feedback?

One approach is linear: students make one commit a time on a single, master branch. In GitHub, teachers can give feedback on a sequential history by commenting on individual commits: view a diff, hover over any line, then click + to start commenting.

For students and teachers alike, this is a straightforward approach, but it’s a little limited. It doesn’t mirror the workflow software development teams use outside the classroom. And what if we want to work collaboratively, in a way that fits with the branch, commit, and merge tools that Git gives us? Then that’s where pull requests come in.

Pull requests build on the branching model of Git. A pull request is GitHub’s way of organizing the merging of two branches, whether it’s within a repository or in between forks. Pull requests make space for collaboration and conversation during the development process. In this post, we’ll walk through setting up a pull request workflow for submitting student exercises and leaving feedback.

Pull requests for individual exercises

By starting with pull requests, even for individual assignments, students can develop the skills and collaboration mindset that will help them when it’s time to work with others on a team. Pull requests allow students to experiment and document their processes and let educators give feedback on their progress. It works a bit like this:

1. The student clones their assignment repository to their local machine.
2. They start a new branch to work on solving a problem.
3. They work on their branch by committing their changes as they go, leaving a trail descriptive commit messages.
4. When they’re ready, the student opens a pull request. In the pull request message, they can describe what problem they’re solving, how they’re thinking about it, and why it’s a good solution.
5. The teacher responds to the pull request by:
   • Adding to the threaded discussion
   • Leaving line-by-line comments on the diff
   • Making a pull request review that combines an overview comment with contextual commentary

Compared to comments on commits, a pull request is a great place for discussion. Authors and reviewers can comment on specific lines, leave Markdown-formatted messages, or give emoji reactions ?⭐. The student can even push new commits to the to-be-merged branch, amending the original pull request.

When the student and teacher are happy with the result, they can press the big green Merge pull request button, bringing the changes into the master branch (or another development branch). After a successful merge, you can tidy up by deleting the dangling branch with a one click.

Pull requests for group exercises

For group assignments, pull requests become an especially important tool for coordinating the work of many. In a collaborative workflow, pull requests open up new ways for educators to understand their students’ development. It works like this:

1. Each student clones the repository to their local machine and starts a unique branch to work on their part of the assignment.
2. The students work on their branches, committing changes and pushing their branch to the shared repository.
3. When each student finishes their part of the assignment, they start a pull request.
4. The students work together to review the proposed changes, discuss improvements or alternatives, and resolve conflicting changes arising from concurrent development.
5. When the students agree on a resolution, they merge each pull request.
6. After the assignment, the teacher leaves additional feedback in the pull requests.

As in individual assignments, pull requests give teachers the chance to peek into their students’ process. The repository’s own Insights tab can give a big-picture view of the students’ work, such as the number of open and merged PRs, frequency of commits, or who has contributed to the repository. A closer look at the pull requests themselves can show the team dynamic: how quickly students respond to PRs, what they say in comments to each other, and how they resolve conflicts.

Groups’ pull requests become a great place for teachers to give feedback, continuing the students’ conversations. Want to bring something to a specific student’s attention? An @mention—the @ symbol followed by a username—notifies the student directly. You can even comment on merged and closed pull requests, just like you would an open one.

Whether your students are working individually or in groups, pull requests are a great way for them to sharpen their workflow and for educators to guide their students. To learn more about using pull requests to work collaboratively, check out the Campus Advisors training module 3—it goes in depth on pull requests, resolving conflicts, and more—or scope out the GitHub Glossary to refresh your collaboration vocabulary. If you’re having any trouble wrapping your head around all this, check out how other teachers are learning about pull requests in the GitHub Education Community.

P.S. Have you been building up your assignment repositories over several semesters?

If so, chances are you have a pretty lengthy commit history by now. Here’s a workflow, inspired by Dr. Diosino, that gives students a clean commit history so they won’t be distracted by your past activity. Here’s how to do it:

1. Create a new repository. This one will be the pristine copy that your students will see.
2. Clone the new repository to your computer.
3. In your clone, pull the changes from the long-lived *repository. Run git pull *
4. Squash (abbreviate, in Git parlance) the history. Run git rebase –root –interactive and follow the instructions Git gives you to collapse many commits into one previous commit.
5. Push the new, abbreviated history to your new repository. Run git push origin.

Written by

Vanessa Gennarelli

@mozzadrella