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

(Eric Ford) #1

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


Classroom vs. custom solution for Jupyter notebook assignments
(topher mykolyk) #2

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.