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.


The Long History of Version Control Systems

Automated version control systems are nothing new. Tools like RCS, CVS, or Subversion have been around since the early 1980s and are used by many large companies. However, many of these are now considered legacy systems (i.e., outdated) due to various limitations in their capabilities. More modern systems, such as Git and Mercurial, are distributed, meaning that they do not need a centralized server to host the repository. These modern systems also include powerful merging tools that make it possible for multiple authors to work on the same files concurrently.


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.


Ignoring Things

This is an optional aside if it comes up or if there is enough time to address it.

Briefly mention the concept of ignoring files with a .gitignore file and direct learners to additional resources.

Along the lines of “What if we have files that we do not want Git to track for us, like backup files created by our editor or intermediate files created during data analysis? Putting these files under version control would be a waste of disk space. What’s worse, having them all listed could distract us from changes that actually matter, so we can tell Git to ignore them. We can do this by creating a file in the root directory of our project called .gitignore. As a bonus, using .gitignore helps us avoid accidentally adding files to the repository that we don’t want to track.”


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.


GitHub GUI

Spend some time showing student around the repository and where to find history on commits etc.


Instructor Note

Take students through the workflow of creating and cloning a repo from GitHub or cloning an existing repository that you want to work with.


Branches

Instructor Note

Using the slides, explain what branches are and when to use them. You can choose to introduce the commands here, but we will practice with the git commands in the next episode as well.


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 clones the repository
  • Instructor B creates a new branch, using git switch -c new_feature
  • Instructor B does some reviewable changes (a simple ‘sum’ function)
  • Instructor B pushes the changes to the remote repository on GitHub using git push origin new_feature
  • 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