GitHub Intro for Beginners

1

Developing Collaborative Documents

Click here for the paired online materials

​

​

Expanded content by by Malvika Sharan

References: Mozilla Science Lab's Study Group Orientation, �Friendly GitHub Intro by Kirstie Whitaker

Visual description: https://learngitbranching.js.org/

Previous trainers: Malvika Sharan, Yo Yehudi, Cassandra Gould van Praag, Esther Plomp, Emma Karoune, Sophia Batchelor, Batool Almarzouq

Arielle Bennett & Anne Lee Steele

1. What is The Turing Way?
2. Github Introduction
3. Hands-on exercises
4. How The Turing Way uses Github

​

https://github.com/alan-turing-institute/the-turing-way, @turingway, CC-BY 4.0. DOI 10.5281/zenodo.7788718

Overview

​

Reference: Library Carpentry: Introduction to Git

This will be a hands-on workshop!

​

Make sure you’re logged in to your Github account!

The Turing Way

A community-led guide to Data Science.

We involve and support a diverse community to make research reproducible, ethical, and collaborative for everyone.

​

@turingway, Image by Scriberia for The Turing Way , CC-BY 4.0, Zenodo: zenodo.org/record/7258956

Credit: This Slide was adapted from a talk co-delivered by Ann Lee Steele and Batool Almarzouq in Durham RIOTS Club: https://doi.org/10.5281/zenodo.7410496

• The Turing Way, incubated at The Alan Turing Institute, was funded from the UK Government’s strategic priority fund investment to help change the culture of data science.
• As of September 2023, 300+ chapters have been written by 450+ contributors from all continents, incorporating third-sector, industry and academic perspectives.
• The project has influenced policy makers: it was used as a best practice use case in the Goldacre review (2022) commissioned by the Secretary of State for Health and Social Care
• It was recommended by the Foundation for Dutch Scientific Research Institutes and Nordic e-Infrastructure Collaboration
• It was cited in the Mayor of London’s adopted Technology Charter for London; and it is often cited in other disciplines.
• It won the 2022 Award for Belonging from OpenUK.

​

Navigating Cultural Change through The Turing Way

Collaboration

​

6

To maximise the benefit of collaboration, we use version control!

The Turing Way project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: 10.5281/zenodo.3332807

Credit: This slide and illustrations are taken from from the Openscapes blog GitHub for supporting, contributing, and failing safely by Allison Horst and Julia Lowndes

The Turing Way project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: 10.5281/zenodo.3332807

• Version control allows us to define formalized ways we can work together

​

• Having a robust and rigorous log of changes to a file, without renaming files (v1, v2, final_copy)

​

• Allow us to quickly undo a set of changes

​

• Help you understand the code and debug

​

​

• Backup

Reference: Library Carpentry: Introduction to Git

Reference: Library Carpentry: Introduction to Git

Git is one of the most widely used version control systems in the world. It is a free, open source tool

​

GitHub on the other hand is a popular website for hosting and sharing Git repositories remotely. It offers a web interface!

Image from Mozilla Science Lab: https://mozillascience.github.io/study-group-orientation/3.1-collab-vers-github.html

A collection of files in a folder or directory, also known as a repository, or “repo.”

Image from Mozilla Science Lab: https://mozillascience.github.io/study-group-orientation/3.1-collab-vers-github.html

I created my repo to store my project details so that my supervisor can collaborate with me, and others can read it

Add information on changes

Credit: This slide and illustrations are taken from from the Openscapes blog GitHub for supporting, contributing, and failing safely by Allison Horst and Julia Lowndes

Image from Mozilla Science Lab: https://mozillascience.github.io/study-group-orientation/3.1-collab-vers-github.html

Revisions and Versions (in real-time)

You don’t save copies of your document, you just save the the life story of the document, or its timeline

Image from Mozilla Science Lab: https://mozillascience.github.io/study-group-orientation/3.1-collab-vers-github.html

We can do all of this on GitHub

• hosts your repositories (projects) online
• helps you work with contributors/collaborators
• provides web interface for version control
• It can be used for project management and communication
• useful for any project where a group of people are working together

Let’s get to know github.com

Step 1: Sign-up

Step 2: Log in

GitHub Exercise 1

Let’s dive in!

Exercise

Make your repo

​

​

“friendly-collab-party”

​

Repository (Repo)

​

A project where all your files are, online or on your computer

19

You know version control.

You created your first repo.

https://www.freeiconspng.com/img/31116

GitHub & Markdown

How to change format of the text?

Markdown (.md) for formatting

Create a README file

• Landing page for your repo
• Add about your project
• Add names/ids of your collaborators
• Invite others with specific skills
• But let’s write it in style with Markdown

Markdown (.md) for formatting

Markdown: what’s that?

Markdown is a simple text “markup” language made for quickly writing formatted text

​

Great for blogs, documentation, and even writing papers.

GitHub automatically renders anything written in Markdown.

This can be specific files, pull requests, issues or comments.

​

Some useful resources:

• https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
• https://www.webpagefx.com/tools/emoji-cheat-sheet

GitHub Exercise 2

Let’s dive in!

Learning Objectives

​

Explain the different GitHub terms

Use these commands online in GitHub

GitHub Terms that we will mention

• Commit
• Branch & Fork
• Pull request
• Merge

27

28

Commit

​

​

Credit: This slides and illustrations are taken from from the Openscapes blog GitHub for supporting, contributing, and failing safely by Allison Horst and Julia Lowndes

Credit: This slides and illustrations are taken from from the Openscapes blog GitHub for supporting, contributing, and failing safely by Allison Horst and Julia Lowndes

Credit: This slide and illustrations are taken from from the Openscapes blog GitHub for supporting, contributing, and failing safely by Allison Horst and Julia Lowndes

Branch & Fork

​

• Branch: It's like a separate path in the same repo where you can experiment with changes without altering the main project. You can decide to keep or discard those changes later within your project's space.

​

Branch & Fork

​

• Branch: It's like a separate path in the same repo where you can experiment with changes without altering the main project. You can decide to keep or discard those changes later within your project's space.
• Fork: It's like making a copy of someone else's entire project to work on independently. You don't need their permission, and you can keep your copy separate or merge it with their changes.

Fork

​

Task: Fork The Turing Way repo

user name

the-turing-way/the-turing-way

Pull Request (PR)

​

• PR: Requesting to combine the work from a forked repo or two branches to the main repo

Fork + Pull Request

If you don’t own a repo and aren’t an official collaborator:

• you will fork a repo
• work on your forked copy of the repo
• make a pull request for the changes you’ve made
• author/owner will decide to merge them in.
• Make friends + Big party!

Pull Request (PR) - 1

​

Task: Edit by adding your details “workshops/github-workshop/2024-nov-intro.md”

Pull Request (PR) - 2

​

Task: Edit by adding your details “workshops/github-workshop/2024-nov-intro.md”

Merge

​

• Merge: combining the work from two different branches together after review

Merge

​

• Merge: combining the work from two different branches together after review

Review before merge: Demo

Users with write access can approve and merge PRs

Create an issue: Demo

​

​

​

Issues are like posts/messages

• Report bugs and errors, propose a new idea, save notes or invite discussions
• Give a descriptive header, provide details

Issue vs Pull Request (PR)

​

• With a issues, you can propose ideas for possible changes, and invite discussions before you make a PR (or do something else).
• With a pull request, you can propose changes, discuss, and iterate on before you merge the changes into the project.

Using Issue & PR Features

​

• Different contributors can see what you are working on and offer help, share thoughts or learn from your work.
• Provide sufficient details, respond patiently, accept constructive feedback and invite collaboration.

Using Issue & PR Features

​

• Advance features: Use labels to sort or highlight relevant PRs and issues (“good first issue”) and tag people for comments/review

Congratulations!

You now know:

Commit

Issue

Pull request

Merge

​

​

There are many more Github features that you can try in your own time.

Photo from @steve3p_0 on Unsplash

Contributing to The Turing Way on Github

Sample issue:

https://github.com/the-turing-way/the-turing-way/issues/3639

The “README.md” is automatically rendered when you visit a repo

Create & manage “Issues”

Your default branch is “main” - but you can switch or add branches here

Download Zip to download the zipped repo onto your computer

Clone to your computer from the web using GitHub Desktop or git command

Fork this repo

Pull Request to add your changes into forked repo

Make “pull request” in your own repo

Branch & PR

​

• Branch: pointers to a specific commit in your repo, temporary places to work through a feature ← you have write access

Pull request in your own repo

​

Pull request

request to add your changes from a branch back into master

Merge

act of incorporating new changes (commits) from one branch to another

“merge” your pull request to your repo

Add collaborators to work as a core part of your team!

Add collaborators

1. Only the owner of a repo can:
• add people as collaborators
• each collaborator can read/write files in the repo
• each collaborator is adding files and other content → making branches → and either directly merging changes in or via pull requests

Settings - add collaborators here

Click here

Add collaborator’s name here

Why and When would I add collaborators?

• You’re building a document and you have teammates.
• You’re writing a paper and multiple people will be writing/editing.
• You’re developing a new course with multiple trainers.
• You are doing an analysis and need your collaborator to review.
• etc...

Add 1-2 of your project members or mentors as collaborators to your “friendly-collab-party”!

Git/GitHub Features

Fork

make a copy of someone else repository

Pull request

request to add your changes into a forked repository

​

Clone

copy a repository onto your local computer

Download Zip

download the content of a repository

Git/GitHub Feature

Project or Project Board

Sort issues, notes, to-dos in a set of columns. These could be:

• milestones
• todo/testing/done
• anything else you like!

Photo from @martzzl on Unsplash

Creating small website with GitHub

Sharing information on your own website

• Oh are we ready yet?
• Do I want people to read what I wrote?
• What if they spot mistakes?

For an Open Research project:

The Answer is Yes!

☀️ Creating a small website

• Share things simply
• Invite people interested in your project to collaborate
• Be open about the project status and invite fixes

Working with GitHub Pages

• A static site hosting service that takes HTML (or related) files straight from a repository on GitHub
• You can host your site on GitHub's github.io domain or your own custom domain

​

​

Creating your site

Reference: https://help.github.com/en/github/working-with-github-pages/creating-a-github-pages-site

See examples

• Simple Theme: https://github.com/malvikasharan/developing_collaborative_document
• Advanced websites using Hugo: https://sgibson91.github.io/
• Advanced websites using Jekyll: https://openlifesci.org/
• Choose from many free and open source templates

70

Glossary & Questions

​

Don’t worry if you haven’t gotten all the terms yet - Play around more & clarify any questions by asking questions on Slack.

​

Happy Making!

Thanks!