Git & GitHub & Open Source

William Durand - November 26th, 2015

Hi! I'm Will, the author of this slide deck.

This slide does not exist in the original deck, but it is useful if you arenot familiar with Reveal.JS, the framework I used to write those slides.

The easiest way to navigate is by hitting [space]on your keyboard. You can also navigate with arrowkeys, but be careful because some slides can benested inside of each other (vertically).

You can also find this deck on Speaker Deck:

https://speakerdeck.com/willdurand/2015

What is NOTthis talk about?

Free Software != Open Source

Why Open Source misses the point of Free Software (according to Richard Stallman)

Git For Newcomers

https://try.github.io

"Macro" Agenda

1. Git 2. Git(Hub|Lab) / Workflows 3. Open Source

Git is a widely used version control system for software development. It is a distributed revision control system.

https://en.wikipedia.org/wiki/Git_(software)

Credit: https://aht.github.io/whatisgit/

Git Tip #1

Local Cherry-Picking

git checkout <other-branch> -- /path/to/file

Merge vs Rebase

Credit: http://surpreem.com/archives/1524

No Fast Forward, Please.

pull = fetch + merge

That's not what you want! No. Really.

git pull --rebase <remote> <branch>

But, Rebase Kills Merges

Preserving existing merges

git pull --rebase=preserve orpull.rebase=preserve (config)

Tadaaaam!

Advanced Features

Git Tip #2

Autocorrection FTW

git config --global help.autocorrect 1

git lol
WARNING: You called a Git command named 'lol', which does not exist.
Continuing under the assumption that you meant 'log'
in 0.1 seconds automatically...
commit 2feb149c8e76d12848f7535a8eb4d51b1c225776
Author: William Durand <will+git@drnd.me>
Date:   Mon Nov 16 14:54:53 2015 +0100

    add badges

...

Git Tip #3

Built-In Auto-Completion

git co<tab><tab>
commit config

git archive

git archive --format zip -o snapshot.zip HEAD

"Export" all files from a given commit into a directory:

git archive --format tar --prefix myapp/ <commit> | (cd /tmp && tar xf -)

Reuse Recorded Resolution

git config --global rerere.enabled true

git merge master
Auto-merging index.html
CONFLICT (content): Merge conflict in index.html
Recorded preimage for 'index.html'
Automatic merge failed; fix conflicts and then commit the result.

git commit --no-edit
Recorded resolution for 'index.html'
[old-branch abcd123] Merge branch 'master' into old-branch

git merge master
Auto-merging index.html
CONFLICT (content): Merge conflict in index.html
Resolved 'index.html' using previous resolution.

Fix conflicts only once with git rerere

git bisect

Performs a binary search across a range of commits to help you find where an error was introduced:

git bisect start

git bisect good abcd123

git bisect bad [badd123]

# The script should end with a non-zero return status when it fails
git bisect run mvn clean test

(My) UsefulGit Commands

Stash

Quickly save current state:

git stash -u 'current state'

Restore it, later:

git stash apply

Or git stash pop but I rarely use it...

Interactive Rebase

git rebase -i HEAD~<number of commits>

pick d1ed4e4 Fix typo
pick b49cb42 Update for lavajug
pick e35510f Add new images

# Rebase 5f167bb..e35510f onto 5f167bb (3 command(s))
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out

Fast Pull & Rebase

git pull --rebase origin master

Atomic Commits

git add -p

diff --git a/test.js b/test.js
index 60ac996..2a57310 100644
--- a/test.js
+++ b/test.js
@@ -1,6 +1,5 @@
 (function () {
-    var i, j;
+    var i = 0, j;

-    i = 0;
-    j = i;
+    j = 1;
 })();
Stage this hunk [y,n,q,a,d,/,s,e,?]? s
Split into 2 hunks.
@@ -1,3 +1,3 @@
 (function () {
-    var i, j;
+    var i = 0, j;

Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]?

Amending A Commit

git commit --amend

git commit --amend -m 'Fix undefined variable j

Fix #123'

Go Back

git checkout -
Switched to branch 'master'

git checkout -
Switched to branch 'feat-undefined-variable'

Also works with merge, cherry-pick and rebase.

(Un)Merged Branch

git branch --no-merged
  develop
  feat-another-feature
  feat-my-feature
  fix-undefined-variable

git branch --merged
* master

Dealing WithPATCH & DIFF

Creating A Patch

git format-patch master --stdout > fix-undefined-variable.patch

From: William Durand <will+git@drnd.me>
Date: Thu, 13 Nov 2015 10:22:17 +0100
Subject: [PATCH] Fix undefined variable

---
 test.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test.js b/test.js
index 760e4eb..60ac996 100644
--- a/test.js
+++ b/test.js
@@ -1,5 +1,5 @@
 (function () {
-    var i;
+    var i, j;

i = 0;
j = i;
--
2.1.2

Changes Overview

git apply --stat fix-undefined-variable.patch

 test.js |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

Test The Patch

git apply --check fix-undefined-variable.patch

No output ==

Then, Apply

git am --signoff < fix-undefined-variable.patch

Applying: Fix undefined variable

commit 4c20f8d517b99638f5379f3f0894ad076d2b6a5b
Author: William Durand <will+git@drnd.me>
Date:   Thu Nov 13 10:22:17 2015 +0100

    Fix undefined variable

    Signed-off-by: William Durand <will+git@drnd.me>

BTW, patch -p1 works too!

GitHub

GitHub is the largest code host on the planetwith over 29.5 million repositories.

Integrated Issue Tracking

Syntax Highlighting

Collaborative Code Review

Pull Request (PR)

Pull Request = Code + Issue + Code Comments

GitHub Pages

Jekyll-friendly
Custom URLs
Built-in layouts

Also, checkout 5minfork.com!

Release Management

Compare View

Protected Branches

GitHub Tip #1

t File Finder

GitHub Tip #2

.patch

https://github.com/your/repo/commit/e0af340837978f80d8cd144a4475.patch

Applying A Commit As A Patch

curl https://github.com/your/repo/commit/<SHA>.patch |git am
Applying: Fix undefined variable

Also, .diff

https://github.com/your/repo/commit/e0af340837978f80d8cd144a4475.diff

hub

git + hub = github

alias git=hub

Clone

git clone random/repo
# git clone git://github.com/random/repo.git

git clone repo
# git clone git://github.com/YOUR/repo.git

Browse

git browse
# open https://github.com/random/repo

git browse -- issues
# open https://github.com/random/repo/issues

Easy Fetch

git fetch ubermuda
# git remote add ubermuda git://github.com/ubermuda/repo.git
# git fetch ubermuda

Checkout

git checkout https://github.com/your/repo/pull/123
# git remote add contributor git://github.com/contributor/repo.git
# git fetch contributor
# git checkout -b contributor-branch contributor/branch

Best way to [work on|review|test] a Pull Request so far!

Apply Commits

git am -3 https://github.com/your/repo/pull/123

Cherry-Pick

git cherry-pick https://github.com/random/repo/commit/SHA
# git remote random git://github.com/random/repo.git
# git fetch random
# git cherry-pick SHA

More!

git fork, git pull-request, merge, ci-status, etc.

hub.github.com

GitLab

GitLab is an Open Source (MIT licensed) web-based Git repository manager with wiki and issue tracking features.

GitLab started a side project in 2011.

In 2015, more than 800 (worldwide) contributors, 10+ employees, and 1.5M raised in seed funding in July.

Getting Started

gitlab.com
git.framasoft.org
On your Raspberry Pi
In your company

Pro-tip: Merge Request ≈ Pull Request

Workflows

Common Workflows

Centralized workflow (with a shared repository)
Blessed repository (with a release manager)
Lieutenant workflow (blessed repo. + trusted lieutenants and a dictator)

Git Flow

"A successful Git branching model"

Well... Maybe not. See this simplegit branching model instead.

GitHub Flow

Understanding the GitHub Flow

GitLab Flow

Pouce Driven Development

👍 + 👍 = Good to merge/ship

Open Source

In production and development, Open Source as a development model promotes a universal access via a free license to a product's design or blueprint [...].

http://en.wikipedia.org/wiki/Open_source

Open-source software is very often developedin a public, collaborative manner.

How To Contribute?

Everyone can contribute.

Fork The Repository

Create A Branch

git checkout -b feature-branch

Eat, Sleep, Code, Repeat.

Submit A Pull Request

But, how?

Look At The CONTRIBUTING File

(If it does not exist, contribute by adding it!)

Write Good Commit Messages

Capitalized, short (50 chars or less) summary

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body. The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Write your commit message in the imperative: "Fix bug" and not "Fixed bug"
or "Fixes bug." This convention matches up with commit messages generated
by commands like git merge and git revert.

Further paragraphs come after blank lines.

A Note About Git Commit Messages

First line ≤ 50 chars, present imperative

"Subject of an email"

Emojis all the things! (like Atom)

(Blank line before details)

Details lines ≤ 72 chars: explain what you did

"Body of an email"

GitHub Flavored Markdown (GFM):

Italics, bold
URL autolinking
Syntax highlighting
Auto-close issues: Fix #123
and more!

Rebase Your Branch

Squash Your Commits

git rebase -i HEAD~2

pick 5335450 add test
pick 4c20f8d Fix undefined variable

# Rebase 35124cb..4c20f8d onto 35124cb
#
# Commands:
#  p, pick = use commit
#  r, reword = use commit, but edit the commit message
#  e, edit = use commit, but stop for amending
#  s, squash = use commit, but meld into previous commit
#  f, fixup = like "squash", but discard this commit's log message
#  x, exec = run command (the rest of the line) using shell
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out

Squashing commits with rebase

Push & Create

Profit!

What Happens Then?

An Open Source maintainer will look at your work.

Pull Request Review

Understand the goal of the PR
Try to reproduce the issue
Try the fix
Test the new feature
Think about edge cases
Write documentation if not provided

What key challenges do integrators face when working with pull requests?

http://www.gousios.gr/blog/How-do-project-owners-use-pull-requests-on-Github/

How To Open Source?

License

https://github.com/blog/1964-license-usage-on-github-com

The README File

project-x
=========

project-x is a better way to achieve this and that, by leveraging the new
API, bla bla bla.

## Usage

...

## Installation

...

## Requirements

...

## Contributing

See CONTRIBUTING file.

README example 1/2

## Running the Tests

...

## Credits

...

## Contributor Code of Conduct

Please note that this project is released with a [Contributor Code of
Conduct](http://contributor-covenant.org/). By participating in this project
you agree to abide by its terms. See CODE_OF_CONDUCT file.

## License

project-x is released under the MIT License. See the bundled LICENSE file for
details.

README example 2/2

The CONTRIBUTING File

Also, checkout Atom's one!

The CODE_OF_CONDUCT File

Badges!

Write Tests & Automate

Be Standard

You Need Feedback!

Twitter
Hacker News
Your team

Attitude

Communication is the key!

Hire People

Dealing With Releases

Semantic Versioning

MAJOR.MINOR.PATCH

semver.org

Changelog

A change log is a file which contains a curated, ordered list of notable changes for each version of a project.

keepachangelog.com

Release Process

Run test suite(s) Update documentation, changelog, version git commit -m "Prepare X.Y.Z release" git tag vX.Y.Z Build artifact (gem build, etc.) Update version number (Z++) git commit -m "Bump version to X.Y.Z+1-dev" git push origin master --tags Publish artifact (gem push, etc.) Publish a GitHub release

Dealing WithEverything Else

Fixing The Code Is Not Enough

Full-Time Hobby

Burnout.

Fat - What Is Open Source & Why Do I Feel So Guilty?

Just do it.

How Many?

Provide Support

... Everywhere

Feeling Guilty

Anger

Source: https://plus.google.com/+LennartPoetteringTheOneAndOnly/posts/J2TZrTvu7vd

But.

Create Things That People Actually Use (& Like)

Make People Feel Good

Receive Overwhelming Feedback

... & Gifts

Let's sum up

Open Source is more thanmaking code available for free.

It is a lot of work!

Care about the people first.

Communication is essential!

Everyone can contribute!

Your First PR

Open Source is more thandownloading code available for free.

Give, don't (only) take.

There are people behind Open Source projects.

Money is still an issue in OSS.

https://coderanger.net/funding-foss/

Thank You.

Questions?

Links

Git & GitHub & Open Source William Durand - November 26th, 2015

Git & GitHub & Open Source

willdurand-slides

Git & GitHub & Open Source

0 4 (function() { var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true; po.src = 'https://apis.google.com/js/platform.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s); })();

git-and-github-and-open-source

Git & GitHub & Open Source

What is NOTthis talk about?

Free Software != Open Source

Git For Newcomers

"Macro" Agenda

Git Tip #1

Local Cherry-Picking

Merge vs Rebase

No Fast Forward, Please.

pull = fetch + merge

But, Rebase Kills Merges

Preserving existing merges

Tadaaaam!

Advanced Features

Git Tip #2

Autocorrection FTW

Git Tip #3

Built-In Auto-Completion

git archive

Reuse Recorded Resolution

git bisect

(My) UsefulGit Commands

Stash

Interactive Rebase

Fast Pull & Rebase

Atomic Commits

Amending A Commit

Go Back

(Un)Merged Branch

Dealing WithPATCH & DIFF

Creating A Patch

Changes Overview

Test The Patch

Then, Apply

GitHub

Integrated Issue Tracking

Integrated Issue Tracking

Syntax Highlighting

Collaborative Code Review

Collaborative Code Review

Pull Request (PR)

GitHub Pages

GitHub Pages

Release Management

Compare View

Protected Branches

GitHub Tip #1

t File Finder

GitHub Tip #2

.patch

Applying A Commit As A Patch

Also, .diff

hub

Clone

Browse

Easy Fetch

Checkout

Apply Commits

Cherry-Pick

More!

GitLab

Getting Started

Workflows

Common Workflows

Git Flow

GitHub Flow

GitLab Flow

Pouce Driven Development

Open Source

How To Contribute?

Fork The Repository

Create A Branch

Eat, Sleep, Code, Repeat.

Submit A Pull Request

Look At The CONTRIBUTING File

0 4