Using Github for Collaborative Codeathons

# Using Github for Collaborative Codeathons
### Hao Ye
### Reproducibility Librarian, University of Florida
### (updated: 2022-07-19)

---
🚀 You've got a team and a project idea and are ready to GO! 🚀

How do you work together effectively??

* Can you edit files from someone else?
* Can multiple people update the project at the same time?
* How do you backup everyone's work?
* How do people outside of the project make contributions?

---
# What is in this talk?

We will go over **basic** concepts and workflow practices.
  - you can get started (even if you haven't used git or github before)

We will conclude with a short hands-on exercise using the GitHub website.

---
This lesson teaches you to:

* articulate the differences between `git` and `Github`
* understand essential features of working in git and github
 - commits as project snapshots
 - branches as ways to experiment
 - remotes and clones
 - collaboration workflow
* create and navigate branches
* create and merge pull requests
* use the "Github Flow" system

---

# Basic Concepts

---

# Version Control

**Version Control**: tools/systems to manage changes to files

--
## You are probably already using version control!

* MS Word will let you "track changes"
* Dropbox / Google Drive store some past versions

---

# Why Learn Git?

Git is version control for **projects**.

You can:
* restore whole project states (i.e. multiple files at once)
* keep track of *who* made *what* changes and *why*
* handle changes in any type of file
* manage work from large distributed teams

---

# Git and GitHub

## (not the same thing!)

---

# Git

* **Git** is the software and the version control system
* default interface is the command line
  - commands have unintuitive names
  - error messages can be obscure
* many other tools improve on the experience
  - graphical interface
  - integration with other things, including GitHub

---

# GitHub

* a cloud platform that hosts Git repos
* unlimited *public* and *private* repos
* size limits:
  - 1 GB for each repo
  - 100 MB for individual files
* GitHub Actions provide continuous integration
  - great for testing or deploying 
  
---

# Git tracks versions for **projects**

---
# Basic Mechanics

* Versioning occurs on the level of a project:
  - projects are called a **repository** (or **repo**)
  - a project is a folder and all of its contents (including subfolders)
* Changes are recorded by taking a snapshot:
  - each snapshot is called a **commit**.

---

![A screenshot of the website https://github.com/uf-repro/friendly-github-intro/commits/main, showing the commit log for the repo of the Friendly Github Intro lesson. Each commit entry has an associated date and time, the author, and the summary of the commit message.](commits_example.png)

---
# Commit Structure

* each commit has a **commit message**
  - 1-line summary (required)
  - blank line
  - further details
* each commit also records **who** and **when**
* good commit messages help you find the right past project state!

---

# Constructing a Commit

* recording commits is done *manually*
  - what files have changed since the last commit? 
    `add` files with changes (including new files)
  - use `commit` command  
  - write the commit message

--
* Why so tedious?
  - You have control over which changes are recorded in each commit

---

# Navigating Commits

* Git generates a unique **hash** for each commit
* You can retrieve a commit by using the `checkout` command and the desired hash
* The file/folder contents will change to reflect the project state for that commit.

*When working in git, think of files and folders as temporary; changes are not saved unless added to a **commit**.*

---
class: inverse, center, middle

# GitHub as a Backup System

---

file backup = store a copy somewhere else

**How do you backup a Git repository?**

Git stores all of the information about commits, history, etc. the `.git` folder of your project
* `.git` is normally hidden

* If you copy the project folder, it will also contain the full git history. (i.e. you can back up separately if you want)

* You can specify other locations to synchronize a git repository to.  
  These are called **remotes**.
  
---
# GitHub is a cloud **remote**

Setup:
1. Create an empty GitHub repo to be your remote location
2. Synchronize this GitHub repo to your computer

Synchronize:
3. `push` will send all new commits on the current branch to GitHub
4. `pull` will retrieve new commits from GitHub

---

# Branches Let You Experiment

---

# About Branches

For simple projects, your project may progress as a line from beginning to end.

If you are solving a new problem, you may want to experiment as you go.

**branches** allow you to label and save work that may or may not end up in a final version to be published.

---

* different branches are separate paths, and in different colors
* each point on a branch is a commit

---

# Creating new branches (GitHub)

---

# Tips for Creating Branches

* choose names that won't overlap with anyone else's:  
  "&lt;name&gt;-&lt;feature&gt;" is a common strategy  
  e.g. "hao-update-readme"

* double check which branch you are in before making a commit!

---

# A Merge/Pull Request Combines Work from Separate Branches

---

# Merges

A **merge** combines changes from separate branches together into a new commit.

* If the changes are in separate files or separate sections of a common file, merging is automatic.

* Otherwise, a **merge conflict** occurs, and you need to manually reconcile the differences for the merge commit.

---
# Example Merge Conflict

---
# Pull Requests

On Github, start by creating a **pull request**.

Pull requests are a way for a maintainer or a team to review and comment on merges *before they happen*.

---
# Creating a Pull Request

---

# Collaborating on GitHub

---
# Sharing Repos

On GitHub, you can add other accounts as collaborators to give them write access.

If you work in the same branch, you have to wait for the other person to finish making changes before you can add yours!

---

# GitHub Flow for Collaborations

* a primary branch, e.g. "main", stores the working version of the project
* updates happen in branches
* when work is ready to be merged into "main", create a **pull request**
* after merging, unneeded branches can be deleted

---

# Benefits

* work in different areas of the project can happen at the same time, in **different branches**
* subteams can work together on shared branches
  - pull request from separate branches to a shared group branch
  - Github enables discussions of pull requests

---

# Exercise

We will now test out the **GitHub Flow** system on your project repos:

1. create a new branch  
  (named "&lt;your name&gt;-readme")
2. in GitHub, add your name to the Team section of the README file, and commit the changes
3. create a pull request to the **main** branch

---
# Takeaway Messages

* **commits** are records of your project
* **branches** are alternate timelines
* **merges** & **pull requests** combine work across branches
* the **GitHub Flow** system lets you collaborate as a team

---
# Thanks

* Don't forget to install the [Git software](https://git-scm.com/downloads) if you want to use Git on your computer.
* I recommend the [GitHub Desktop](https://desktop.github.com/) software if you want a graphical client.
* ["Understanding the GitHub flow"](https://guides.github.com/introduction/flow/) has more details on the GitHub Flow system