Instructor Notes

This lesson teaches participants how to collaborate with git and GitHub in one day.

Teaching a 2-day Good practices in research software development workshop

Often we also add a 2nd day with this lesson: https://esciencecenter-digital-skills.github.io/good-practices-lesson/, which builds out the basis of git and GitHub to a 2-day Good practices in research sofware development workshop

Timing

It is quite ambitious to teach git and GitHub properly in one day. Here are some tips to make it work: - Park advanced questions In the ‘introduction to git’ part: ignore the temptation to answer advanced questions. (You can of course do this individually during exercises). - Focus on the bare minimum There is so much to explain about git, but focus on the bare minimum that participants need to be able to collaborate on GitHub.

Automated Version Control

Instructor Note

Original lesson material: https://swcarpentry.github.io/git-novice/ Slides: https://esciencecenter-digital-skills.github.io/digital-skills-slides/modules/git-lesson/git-slides, until https://esciencecenter-digital-skills.github.io/digital-skills-slides/modules/git-lesson/git-slides#/4.

The slides can be used to explain the concepts introduced in the text here.


Setting Up Git

Instructor Note

There are no slides for this episode. Explain what a command line is, why it is useful, and why we use it in this workshop. Participants are often new to the command line and don’t get why we not use a git gui. Only focus on the bare essentials for setting up git. We shall use nano editor so that everyone is on the same page.


Creating a Repository

Instructor Note

Introduce here the story of Wolfman and Dracula. The examples make more sense if you introduce the story. Here we suggest referring to ‘The Holy Realms of Git’ slide: https://esciencecenter-digital-skills.github.io/digital-skills-slides/modules/git-lesson/git-slides#/5 to introduce the idea of repository and .git.


Tracking Changes

Instructor Note

We suggest to use slides. From slide 5 onwards: https://esciencecenter-digital-skills.github.io/digital-skills-slides/modules/git-lesson/git-slides#/5 Please switch back and forth between command line and slides when necessary.


Exploring History

Instructor Note

There are no specific slides for this episode. You could consider keeping the slides open to the episode on the basics of Git, to show the visual representation of the changes in the repository.

Consider doing this episode as a demo and not as live coding if time is short. The aim is to demonstrate to participants the possibility to go back and forth through the git log, which is enough for an introduction to git. In practice, you only use this feature occasionally.


Ignoring Things

Instructor Note

There are no slides associated with this episode. We suggest doing a demo here instead of live coding. Focus on getting the concept of ignoring files with a .gitignore file across, instead of getting learners to fully be able to use the syntax.

We suggest ignoring (haha) the exercises, since the main idea of a .gitignore file comes across without exercises.


Remotes in GitHub

Instructor Note

There are no slides associated with this episode. Take a dedicated moment right before this episode to check succesful completion of particpants’ SSH setup and help out people who did not succeed yet. You will need 15-30 minutes for this, so prepare an optional exercise for people that are correctly setup.


Collaborative Version Control - Centralized

Instructor Note

Teaching is done as a pair of instructors. Instructor A acts as the owner of the repository, instructor B as a collaborator (internal or external).

First we show the centralized workflow all in the browser using Github:

  • instructor A creates an issue (for example create ‘sum’ function)
  • instructor B picks up the issue
  • Instructor B creates a new branch (good to do this explicitly)
  • Instructor B does some reviewable changes (a simple ‘sum’ function)
  • Instructor B opens a new pull request.
  • Instructor A reviews and approves the PR.
  • Instructor B merges the pull request.
  • Use Github repo’s insights -> network to visualize what just happened

Collaborative Version Control - Distributed

Instructor Note

Teaching is done as a pair of instructors. Instructor A acts as the owner of the repository, instructor B as a collaborator (internal or external).

Now we show distributed workflow. All in the browser using Github:

  • Instructor A removes instructor B
  • Instructor B now submits an issue
  • Instructor A responds to issue asking instructor B to pick it up
  • Instructor B forks repo, does some changes, and submits PR
  • Instructor A reviews the changes
  • Instructor B implements the changes
  • Instructor A merges the pull request
  • Use Github repo’s insights -> network to visualize what just happened