Contribute with Forks on Github

Note: This tutorial is incomplete. It will updated by Friday, July 16th.

Video recording for this session

Table of contents

• Introduction

• 1. Forking vs Cloning

• 2. Contributing as a non-collaborator

  • 2.1 penguin creates a new repo

  • 2.2 penguin generates initial content

  • 2.3 penguin pushes the package to github

  • 2.4 puffin installs the package

  • 2.5 puffin forks the package repository

  • 2.6 puffin sets up repo for contribution

  • 2.7 puffin adds more functionality to the package

  • 2.8 puffin pushes updates to the fork

  • 2.9 puffin creates a pull request

  • 2.10 penguin examines and resolves the pull request

Introduction

Last week we looked at better ways of contributing to a repository on GitHub when you are a collaborator. This may not always be the case. Often times, development of open source software is brought about by contributions from active users who are not official collaborators on a project.

Take any popular R package on GitHub and look at how many people contributed code towards continuing development of that project. Chances are that many of them are not official collaborators. This week, we will learn how to contribute on github in such circumstances using forks.

1. Forking vs Cloning

• What is forking anyway? Let’s visit Github page for one of the tidyverse packages: purrr.

• Take a look at the top right corner on the package page. You will see something like above. This indicates how many people are watching the repo for updates (watch + star) and how many have forked the repository for further development.

• Assuming you are currently logged into your account on github, click on the Fork button on the purrr repo. Notice that GitHub will transfer you to your own account where a copy of the purrr repository will be created. It will appear as follows:

• The difference between forking and cloning should be clear now. Cloning is making a copy of a repo on your local computer, whereas forking is doing the same thing on GitHub.

2. Contributing as a non-collaborator

• Our workflow for Github collaboration begins here. You will still need two github accounts like last time, but we will work them a bit differently now.

2.1 penguin creates a new repo

• First, using your original account, create a new repo, and name it mkhist. Keep it public.

• Unlike last week, you will not create any collaborators on this repo.

2.2 penguin creates a R package

• On your local computer, create a new folder named after the repo and generate a new README.md.

cd ~/Github && mkdir mkhist && cd mkhist

git init

touch README.md

• Write an R function to generate histograms from each variable of the dataframe

library(tidyverse)

mkhist <- function(x){
    print(x %>% head())
    x %>% gather() %>% head()

    ggplot(gather(x), aes(value)) +
        geom_histogram(bins=20) + 
        facet_wrap(~key, scales='free_x')
}

2.3 penguin pushes the package to github

2.4 puffin installs the package

2.5 puffin forks the package repository

2.6 puffin sets up repo for contribution

2.7 puffin adds more functionality to the package

2.8 puffin pushes updates to the fork

2.9 puffin creates a pull request

2.10 penguin examines and resolves the pull request