Workflow for Combining the Benefits of Jupyter Notebooks with GitHub version control and feedback

I’m teaching a class in high-performance computing. Their assignments are distributed Jupyter notebooks (using a Julia kernel), so as to integrate text, links, equations, plots, and starter code. However, I also want students to learn good programming practices, such as using version control, code review, pull requests, etc. Also, I want to use GitHub.com/GitClassroom to quickly see what students have changed and efficiently provide feedback on specific lines of code.
I also wanted to be able to easily review and merge small changes suggested by students or other instructions.

Unfortunately, the native Jupyter notebook format makes the diffs unreadable to normal humans, rending GitHub not so useful. I searched and asked by Office of Digital Learning, but couldn’t find an existing way to get the benefits of both Jupyter and GitHub.

Therefore, I’ve created a workflow that is described on the course website. It uses the Weave.jl package’s convert_doc to turn my initial Jupyter notebook (where I do the exercises) into a Julia MarkDown file. Then, it runs convert_doc again to create a starter notebook for the students. Before submitting, then run convert_doc to generate a Markdown version of their notebook. Finally, they submit a pull request and I provide feedback on the markdown versions of the notebooks on github.

It’s a little bit involved, but with a good checklist, I nearly got it right on the first try for the second assignment. Some of the commands are specific for my course, but it should be easy to see how to adapt it for another course.

I’d be interested to hear if others have tried something similar, have suggestions for improving this workflow, or have found a completely different solution for combining the benefits of Jupyter notebooks and GitHub for programming classes.

Thanks,
@eford

2 Likes

Thanks for sharing this. Impressive legwork you have put in. Jupyter notebook may find its way into my courses next year; if so, I will be taking heavy advantage of your model. Thanks for posting.

@eford

or have found a completely different solution for combining the benefits of Jupyter notebooks and GitHub for programming classes.

You can use ReviewNB to review Jupyter notebook pull requests on GitHub. It will show you rich diffs & ability to comment on notebook cells.

David Shean, assistant professor at UWash, is using ReviewNB for his spring course this year. He talks about the same problem in this thread.

Disclaimer: I built ReviewNB

Thanks for your work on ReviewNB and for bringing it to my attention.
In a classroom setting, I default to students’ repositories being private (free thanks to GitHub classroom), so that their mistakes and my feedback is private. Does ReviewNB plan to offer a free plan for educational settings that need to make use of lots of small private repositories?
Thanks.

Does ReviewNB plan to offer a free plan for educational settings that need to make use of lots of small private repositories?

We do not offer free plan for private repositories. We’ve kept our prices low enough that it’s affordable for academic institutes as well. If you subscribe to a Standard plan then you can create unlimited number of repositories & you can only subscribe for the months when you have an ongoing class that’s using it.

1 Like

Is there any student discount for students if so please message me at Instagram
Thanks
Sourabh

© 2017 GitHub, Inc.
with by
GitHub Education