Push-Pull and All That
A Guide to GitHub & Collaborating

Zigfried Hampel-Arias

5 June, 2019 / Timeless

Slides

https://zhampel.github.io/github-contributing-guide

Contact

Find me on:

Overview

• Version Control
• Brief Terminology
• Contributing to Personal Repos
• Contributing to Repos in Teams

Version Control: Why?

• Keep track of code, its changes, all in one place.
  • Multiple versions of code
  • Doc changes from you (troubleshooting) or others (PyTorch, e.g.)

• Ability to collaborate
  • Experiment without interferring others' work
  • Tracks who-done-it and when
  • Industry Standard -> Future Positions

• Risky not to use, plus it's FREE!

Personal Disclaimer

Not a definitive guide to using git

• I won't pretend to be an expert
• Countless resources with further details
  • GitHub Book
  • GitHub help articles
  • StackOverflow git tags
  • Git and version control Q&A

Slides provide guidelines

• Outlines majority of expected usage/reqs
• Provides a streamlined workflow for collaborative teams

Main goal: understand & encourage following these guidelines

Terminology Overview

Places	Actions	Communications
repositories	fork	remote
fork	push	issues
upstream	pull	pull request
local	merge	.
.	commit	.
.	fetch	.

Sort of loose, conceptual categories for these slides...

Repositories

• Magical place (GitHub server) where your project lives
• In git, repo officially ends in .git
• Well organized, documented (README, checklist)

Repo in terms of version control

Origin repo has sequentially tracked versions

• One master, may have many branches
• Dots represent changes to project along specified branch

But how to make these changes?

Local Working Copy

One must pull the origin to workstation for local repo clone/copy.

• git clone https://github.com/<username>/<repo>.git

Local Work

Can make changes locally on master branch or topically named branch:

• git checkout -b leafy_branch

Local Work

As a quick aside, always good to run frequently

• git status to get more info
  

Can also check what available branches are present via

• git branch

Local Commits

When work is done, prep via add and commit!

• git add <modified_file_list_here>
  
• git commit -m '<meaningful short message of changes>'
  This preps changes in a buffer ready for the main repo

Update the Origin

Push local work to origin

• git push
  
• git push origin X
  depending if changes to master or X
  

Personal Repos Wrap-Up

These commands are used more for personal repos, for which you are the creator.

So what if you have friends?

Repo is Somewhere Else on GitHub

You must fork the repo! Done directly on GitHub
Makes a copy of the repo at its current state in your account

Roles Change Once Forked

Now treat forked repo as origin, as before

Won't be working on upstream till later.

Local Work Again

After the fork, origin is repo in your account
Repo you forked from becomes upstream, pull/push from origin as usual


What about if changes are made since to the upstream you forked from???!!!

You sync them up!

Create a remote to the upstream repo

• git remote add upstream https://github.com/<someones_username>/<repo>.git
  
  

You sync them up!

Then sync the local one by fetching the upstream, then merging it and the local master

• git fetch upstream
• git checkout master
• git merge upstream/master

Now get to work as usual...

• Make new branches and write new code
• Add changed files, commit and push to origin
  
  

After pushing...

So far, push only changed your forked repo, the origin.

Ask changes to be reflected in upstream via Pull Request

Alerts maintainer to review requested changes. One should:

• Check if changes solve an open issue, otherwise open a new issue.
• Statement in PR box detailing changes.
  • Assign yourself
  • Request review to look for errors, conflicts, etc
  • Do Not merge, only done by the reviewer!

Collaborative Effort

Comparison

Collaborative Work	.	Personal Repo Work
	.

Some Best Practices & Comments

General

• Use git status often
• Commits short: git commit -m "Adds input feature x to script y"
• Add tech advisor as collaborator

Personal Repos

• Can work on master, branches show mastery...

Collaborative Work

• Extension: contribute safely to codebase, avoid conflicts
  • Addition of fork, remote/fetch prior to work
  • PR after normal steps when code is deliverable (code review...)
• Never merge a PR to a codebase unless you are the reviewer.

Summary

• Hopefully, the functionality of GitHub is clearer
  • Set of commands for 90% work
  • Potentially improve performance of team
  • Provide systematic review in main codebase

• Is safest, most efficient manner to streamline contributions to repos in teams

• Finally, example checklist you can test commands on in this very repo!

Thank you for your attention!

Any Further Questions?

Command Line Sequences

Personal Repos

• Create a new repo named repo_name on your GitHub :)
• On your work station, clone the repo
  • git clone https://github.com/<your_username>/<repo_name>.git
  • cd repo_name
• You are now in a local copy of the origin-al repo

• You are on the master branch until you decide to make a new branch
  • git checkout -b <new_branch>
  • git branch or git status to get more info
• Can checkout other existing branches easily
  • git checkout <other_branch_name>
  • git checkout master of course
• For more info
  • git branch or git status

Personal Repo - Command Line Sequence

• git clone https://github.com/<your_username>/<repo_name>.git
• cd repo_name
• git checkout -b <new_feature_branch_name>
• git add <modified_file_list_here>
• git commit -m '<meaningful short message about the changes made>'
• git push origin <new_feature_branch_name>
• If pushed to master branch, no worries. Otherwise, can go to your repo on GitHub and submit a Pull Request.

Contributing to Repo - Command Line Sequence

• Fork the Repo
• git clone https://github.com/<your_username>/<repo_name>.git
• cd repo_name
• git remote add upstream https://github.com/<upstream_username>/<repo_name>.git
• git remote -v
• git fetch upstream
• git checkout master
• git merge upstream/master
• If fixing/adding, good idea to submit a ticket. Assign yourself, add labels, etc.

Contributing to Repo - Continued

• git checkout -b <new_feature_branch_name>
• Do what you do best
• git add <modified_file_list_here>
• git commit -m '<meaningful short message about the changes made>'
• git push origin <new_feature_branch_name>
• Go to your repo on GitHub and submit a pull request! Can request reviewer, assign yourself, add labels, etc.
• After PR accepted go back to git fetch upstream step and keep contributing!