add lesson on github

[tracykteal]

Related to https://github.com/Reproducible-Science-Curriculum/publication-RR-Jupyter/issues/33 it would be good to have a lesson on github. It's a pretty standard way of sharing Jupyter notebooks, and a github module was one of the most requested at the R Reproducible Research workshop.

This lesson could come after the one on exporting notebooks. Narrative: Some people just need the pdf or the HTML to see the results, maybe people like your PI or for a report. Other people, such as collaborators, or future you, might want the notebook itself, so they can be able to run the analysis themselves.

The lesson wouldn't need to include everything about forking and merging. We can point to the full SWC git lesson for more information. This one could include

• creating a github repo
• edit the README on github
• clone the repo
• putting Jupyter notebooks in the repo
• pushing those notebooks to the repo
• show how you can now see it on github, so now other people can see it, or clone it for them to use
• make a change to the notebook
• push the changes to github
• show that diffs aren't that useful to be able to track in this particular case
• show how you can go back to, still have access to previous versions

Much of this content could likely come from the existing SWC github lesson.

A lesson like this would set it up, so you could have an exercise on putting a github repo on Zenodo for a DOI.

This also sets it up for mybinder.

[elliewix]

I would propose using the GitHub desktop application for this. I do nearly this exact demo with my students and it works well. It also introduces the vocabulary. There is an issue that the GUI changes, but if you focus on the vocabulary it should be reasonably easy to maintain. There's also the possibility that you could write is generically enough that the instructor could use either.

I had about 20 students this semester do a programming project with no GitHub or version control experience do this process on their own after a really brief demo. (GitHub was a required element). I only had one email with a question about it. So I have that metric at least.

Writing up more detailed directions about this process is actually on my todo list for the next two weeks, so I could rough some things out here or share my notes.

[tracykteal]

That sounds like a great idea! I was worried about installation and command line issues. This is the perfect solution, and even tried and tested. Thanks so much.

If you could share your notes or have a chance to rough something out that would be terrific.

[choldgraf]

A quick thought - is there a place for more "meta" material (like github lessons)? It seems like it'd be in the spirit of the carpentries not to have two separately maintained github tutorials, but to have one base tutorial that could be modified for specific lessons.

[elliewix]

Parallel materials are always less than ideal. I think that I can write this in such a way that someone can adapt the directions to any git platform or UI on the fly.

[hlapp]

Note that @iamciera taught such a lesson at the 2nd teaching workshop, and @kcranston did so at the 3rd teaching workshop. I believe the experience was mixed (perhaps @iamciera and @kcranston can add details, but my recollection in a nutshell is that the UI and avoiding installation as well divergent desktop UI issues were great, but invariably the question came up how they would apply this to their own research products, revealing that the instructors all use either the command line or a desktop UI, and rarely the web UI). This was all using the R Markdown version of the curriculum.

So there is a pitfall here of teaching something that the instructors purposely use something else for. Perhaps that's less difficult to navigate around for Jupyter Notebooks than for R Markdown documents.

[elliewix]

I have many of these sections written now, and I've included examples of how someone might incorporate command line & UI. I have some written on when you would use the website, but can add more. These are good comments from previous instruction.

[iamciera]

The first time that the Reproducibility curriculum was taught Git / Github was introduced but not taught. The feedback reflected that many students want to learn Git /Github. So, in light of that, we tried two lessons for the R version of the curriculum.

1. I taught one workshop with the Github GUI. The main problem with the GUI is that there are many different versions of the GUI. There are different versions depending on which Mac OS you have and differences between Mac and PC GUIs. The vocabulary is not consistent between all versions of Github GUI (which also is different from command line vocab). Every step was a headache because everyone was working with different versions. This made everything quite difficult when teaching, but again, that was a few years ago and maybe the different versions problems have been fixed?

2. I helped create a Github only lesson that I believe Karen taught. They collaborated on the same repo, so the students never brought the repo onto their own computers. The main argument against this lesson is that the students didn't get a thorough understanding of Git / Github and many were left with questions and lack of understanding on how to implement.

• One aspect that I thought was very useful when I taught was introducing a collaborative project on Github, I think I choose ggplot. I showed them the contributors sections, diffs display, commit history, issues, ect. It was a good way to introduce them to Github while displaying the power of Git.

I think what @tracykteal outlined is great and if the instructor is well aware of all the differences with the Github GUIs, then it should be relatively smooth (famous last words...)

[tracykteal]

This all sounds great. Should we create a separate repo for this, so there's an RR-Jupyter-git lesson? To make it more modular, so it could be more general?

[elliewix]

@iamciera in the past the GUIs seemed closed together. Maybe it would be helpful to compile some GUI screenshots of Mac/Windows/etc versions for instructor notes. Can someone post some windows screenshots? I think there might not be a linux version, but there may be other options... I can try and incorporate notes for both GUIs as part of the lesson.

For command line novices and the version control nervous, I'd rather fight with GUI differences than command line git.

[burkesquires]

I think that version control, and thus git and GitHub are a necessity. I agree that using the GUI is the way to go. I use the GUI almost daily and it is great!

[elliewix]

OO these youtube videos are super helpful. I'm adding in lots of notes for windows vs mac.

[elliewix]

OK, I have a first pass up here: https://github.com/elliewix/github-training-brain-dumps/blob/master/github_directions.md

I'll be working on revisions and then forking this for my class' needs later this week.