Magicians might be able to conjure up perfect pull requests, but for the rest of us, there’s getting feedback and revising. By combining draft pull requests and review requests, educators can teach a collaborative mindset and best practices from the industry. Let’s see how this works in action, through an example.

Sarah is a student taking CS1 with Dr. Root. To complete an assignment, Sarah needs to demonstrate writing code and using Git with a pull request.

It’s never too late to revise (a draft pull request)

Sarah starts to work on an assignment in a local branch and commits a change. Then she pushes her initial change to the assignment repository on GitHub before opening a draft pull request. By creating a draft, Sarah signals to Dr. Root that the pull request is still a work in progress. And GitHub prevents Sarah (and others) from merging the pull request.

While the pull request is still a draft, Sarah can iterate on a solution to the problem by pushing more commits. Unlike working privately on a local branch, working on a draft pull request offers Sarah the benefits of GitHub’s features and integrations:

She can use a task list to keep track of incomplete work.

She can mention a teaching assistant to get clarification on a requirement or get help on a particularly thorny bug.

She can even get test results from Travis CI with each new commit.

When Sarah is content with her work (or a deadline looms), she can tell Dr. Root that the pull request is ready for feedback by clicking Ready for review and requesting a review from Dr. Root. Review requests are a quick way to ask specific collaborators to review your pull request. And by marking the pull request as ready for review, Dr. Root now has the option to merge the pull request.

Soon Dr. Root notices Sarah’s pull request in her list of requested reviews. She reviews the pull request by providing feedback and suggesting changes—she might also leave a comment to ask questions or link to documentation.

After Dr. Root responds to Sarah’s pull request, she can follow up by pushing more changes to her branch and responding to any additional questions. Sarah can quickly ask Dr. Root to take another look at the pull request by re-requesting a review—in a single click.

Through all of this, Sarah gets a taste of the process that software developers in the industry use to squash bugs—collaboration and continuous improvement. This back-and-forth process of revising can continue, or if Sarah and Dr. Root are satisfied, they can merge the pull request.

One workflow, many possibilities

By working with draft pull requests, Dr. Root can gain insight into her students’ process. She can track students’ progression from draft, through review, to merge. These checkpoints can help identify students who may need extra help to succeed—even before the students themselves realize they need it.

Tracking students’ progress is just one possibility. There are many opportunities to use this framework—drafting, revising, (re)reviewing, and merging—as you teach. For example, students in software engineering courses can seek preliminary feedback from teammates, and instructors can evaluate students’ group collaboration. Or teaching assistants can use checkpoints to incrementally grade assignments, awarding partial credit at each stage in the process.

However your course is structured, draft pull requests and review requests can be a great way to foster a practice of iteration and improvement in your students. How are you using pull requests in your classroom?

Share your tips with the community