Contributing to carpentry lessons with GitHub

25 Jul 2016

tl;dr

Set up your remote upstream and merge updates from there

Fork the repo you want to work on.
Clone that repo down, e.g., git clone https://github.com/USERNAME/library-shell/
So you can fetch changes from the originating repo, add remote reference there: git remote add upstream https://github.com/data-lessons/library-shell/ (you can see your remotes by git remote -v)
Get changes from upstream: git fetch upstream
Merge those changes locally: git merge upstream/gh-pages
Repeat Number 4 & 5 above before you begin a new unit of work below to insure you have the latest base version of the lesson

Do work in a local branch and submit changes to the lesson repo

Start with the latest version of the upstream lesson (see above)
Create a branch for your improvements: git checkout -b new-lesson-improvement
Install Jekyll if you want to preview your changes locally
Run make serve to preview locally, typically at http://127.0.0.1:4000/
Once done with your work as you see fit, run git add, git commit, and then git push origin new-lesson-improvement up to your forked repository.
Make a pull request from your repo in GitHub (this tells the upstream maintainers: hey, pull my improvement into the upstream repo)

Getting set up to improve lessons

After we taught Library Carpentry here at UCSD, we sat down and worked through the workflow for contributing to Carpentry lessons. Matt Critchlow, our IT Dev Manager, walked us through the CONTRIBUTING.md document and I worked up the steps below from our meeting.

One of the confusing aspects on translating the common fork/pull-request development workflows is that most of the documentation found on the web is spelled out for master branches. This is because, by convention, the default branch when you initialize a repository in GitHub (or locally) is named master. However, with the Software/Data/Library Carpentry lessons the default branch is set to gh-pages. This is mainly for ease, because the web version of the lessons live in this branch and this is where Software Carpentry wants the work to go for contributions. Also, on GitHub, commits to this branch will be processed by Jekyll, a static site generator, making the nice lesson webpages we use in class. The main thing to know is that in Software Carpentry lesson land, when you see master in Git help or online documentation, you can mentally substitute it with gh-pages. Hopefully, this will help folks new to git contribute more to the lessons.

Update 2016-08-28: Corrected the Getting changes from the upstream default branch gh-pages section to remove using git status to check changes in the upstream remote as this won’t work! git fetch upstream is the right command to pull down any changes that may have been made.

Setup your fork and local clone

Fork a lesson you want to contribute to, for instance, data-lessons/library-shell. Forking will create a linked copy of the repository in your own GitHub account.
Clone the library-shell project to your local machine (USERNAME - your GitHub user account name). Having a local copy allows us to edit locally using our favorite tool, create branches for discrete work and keep the local repository in synch with data-lessons/library-shell:
```
$ git clone https://github.com/USERNAME/library-shell/
```
clone grabs the repository and makes a local copy. It will create the directory (named for the repository name by default) and sets up the linkages between your clone and the remote repository (called origin). Let’s confirm this by running git remote -v.
```
$ cd library-shell
$ git remote -v
```
```
origin  https://github.com/ucsdlib/library-shell.git (fetch)
origin  https://github.com/ucsdlib/library-shell.git (push)
```