GitHub for Collaboration

Malvika Sharan

​

​

​

​

References: Mozilla Science Lab's Study Group Orientation, �Friendly GitHub Intro by Kirstie Whitaker & GitHub Collaborating Document by Malvika Sharan and Esther Plomp

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

​

All slides are CC-BY 4.0

Open Life Science

Links

GitHub for Collaboration - Line 70 onwards on the Etherpad

• Training materials: https://malvikasharan.github.io/developing_collaborative_document/
• Github link: https://github.com/open-life-science/ols-4/blob/master/week-05/week-05-notes.md
• Cheatsheet: https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf

​

Roadmap

• What is Version Control and Why it’s Important
• What is GitHub
• GitHub and Markdown
• Exercise: adding a README.md
• Exercise: editing a GitHub page and making a PR
• Exercise: Make your first Git Page
• Other features of GitHub

Collaborative

Documents

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

There are challenges in developing collaborative documents...

​

​

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

There are challenges in developing collaborative documents...

​

• Asynchronous and conflicting edits, location, time zones, and

VERSIONS!

Collaborative

Documents

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

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

Revisions and Versions

Images from Mozilla Science Lab, Illustration by Scriberia and The Turing Way

Images from Mozilla Science Lab, Illustration by Scriberia and The Turing Way

Version Control

Management of changes, called revisions, to a file

• Simple file versioning with v1.0, v1.1, …
• Simple tools like Google Drive, Dropbox...
• Advanced tools: git (local version controls system)

​

Revision: Change associated with a timestamp and details like what changes were made, who changed them, why etc.

Version Control

Management of changes, called revisions, to a file

• Simple file versioning with v1.0, v1.1, …
• Simple tools like Google Drive, Dropbox...
• Advanced tools: git (local version controls system)
• Benefits: collaborate in real time, store history, go back to previous versions

We can Collaborate on GitHub

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

GitHub wut!?

Slide by Sophia Batchelor, https://zenodo.org/record/5070361

• 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

PAUSE!!!

Do you have a GitHub Account?

​

Go to https://github.com/

​

• Create an account using the sign up
• Login

​

Slide by Sophia Batchelor, https://zenodo.org/record/5070361

GitHub Exercise!

​

First Repo

​

​

“friendly-collab-party”

​

Repository (Repo)

​

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

First Repo

Learn more in The Turing Way chapter: https://the-turing-way.netlify.app/collaboration/github-novice.html

You created your first repo.

CONGRATS!!

Slide by Sophia Batchelor, https://zenodo.org/record/5070361, https://tenor.com/view/flower-power-rainbow-yeah-gif-7304860

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.

​

You may have used it in HackMD.

Markdown (.md) for formatting

Create a README file

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

GitHub Exercise!

​

GitHub Exercise: Create a README.md

Learn more in The Turing Way chapter: https://the-turing-way.netlify.app/collaboration/github-novice.html

GitHub Exercise: Create a README.md

Write whatever you would like!

​

• about the project
• vision statement
• roadmap
• for today, the project name

GitHub Vocabulary

• Commit
• Branch & Fork
• Pull request
• Merge

Commit

​

Saving a version of file(s)

​

• ‘commit’ changes with message (i.e.‘My first commit’)

​

Branch & Fork

​

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

open-life-science/repo-name

Branch & Fork

​

• Branch: pointers to a specific commit in your repo, a temporary place to work on a feature ← you have write access
• Fork: copy of repo that is an entirely independent repo ← no need of write access or intent to merge with the main

malvikasharan/repo-name

Fork

​

Task: Fork OLS-4 repo, https://github.com/open-life-science/ols-7

user name

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

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 collaboration easy - bring in new people!

Pull Request (PR) - 1

​

Task: Edit by adding your details “/week-05/week-05-notes.md”

Pull Request (PR) - 2

​

Task: Edit by adding your details “/week-05/week-05-notes.md”

​

Review: Demo ☀️

Users with write access can approve and merge PRs

Merge

​

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

Merge

​

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

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
• You have already done it!

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.

Breakout 1

• Create a PR on OLS-4 repo
• If time allows
• Create an issue in your own repo
• Create a PR on a different (a colleague in your breakout room) repo

Using Issue & PR Features

​

• Advance features: Use labels in your repo to sort or highlight PRs and issues (“good first issue”) or 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 @martzzl on Unsplash

Creating a 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

​

​

Breakout 2: 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

51

Glossary & Questions

​

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

Follow on with the remaining materials in your time.

​

After this workshop

Project Board/Management 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!

More on this next week!

More on “pull request”

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

Adding additional files to your repo

Add a license

GitHub can add a license for you

when adding a new file named LICENSE...

Software (choosealicense.com)

​

​

​

Content (creativecommons.org): CC0, CC BY, CC BY-SA

​

​

​

Data: CC0

Add additional files

As discussed in the previous cohort calls:

• CONTRIBUTING.md
• Code_of_conduct.md
• roadmap.md
• ...

Adding your project members or mentors as collaborators to your repository

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

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

Learn more in The Turing Way chapter: https://the-turing-way.netlify.app/collaboration/github-novice.html

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

Glossary & Questions

​

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

​