79 lines
3.2 KiB
Markdown
79 lines
3.2 KiB
Markdown
---
|
|
title: "Contributing to Open-Source with Github"
|
|
kind: article
|
|
slug: contributing-to-open-source-with-github
|
|
created_at: 2011-11-09
|
|
tags:
|
|
- git
|
|
- rebase
|
|
- github
|
|
- flow
|
|
- fork
|
|
- upstream
|
|
---
|
|
You want to contribute to an open-source project, but are scared away by all the git-complexity involved? This small guide will help you out.
|
|
|
|
<img src="https://ariejannet.s3.amazonaws.com/content/github.png" alt="Octocat" align="right" />
|
|
|
|
## Step 1 - Fork, fork, fork
|
|
|
|
First create a fork of the original project. You can do this easily by clicking the "Fork" button on the top of the Github project page. This will give you your own copy (fork) of the entire repository.
|
|
|
|
Then, check out your fork:
|
|
|
|
git clone git@github.com:ariejan/repo-name.git
|
|
|
|
## Step 2 - Contribute
|
|
|
|
Before you start writing code there are a few tasks you need to perform:
|
|
|
|
* Are there tests for this project? Are they all green? If not, fix this first. (using this same step, of course)
|
|
* Create a new branch: `git checkout -b fix_for_this_or_that`
|
|
* Red-Green-Refactor (e.g. write code)
|
|
* Commit your changes (in your `fix_for_this_or_that` branch).
|
|
|
|
## Step 3 - Sharing your contribution
|
|
|
|
With your contribution done, don't merge it back into `master`. `master` is your way of receiving changes from the original (upstream) repo (see step 4).
|
|
|
|
First push your branch to Github, so you can share it with others.
|
|
|
|
git push origin fix_for_this_or_that
|
|
|
|
You should now see this branch in your Github project page. You'll also notice there's a "Pull Request" button at the top. Click it if you want the project maintainer to pull your `fix_for_this_or_that` branch into the main project.
|
|
|
|
## Step 4 - Keeping up-to-date
|
|
|
|
Over time the `master` of your fork will start lagging behind. Because you did not merge any of your code changes into the `master` of your fork, you can update it easily.
|
|
|
|
Before you can pull in changes you must add a git remote for it. You can use the _Git Read-only_ URL for this.
|
|
|
|
git remote add upstream https://github.com/some_one/some-repo.git
|
|
|
|
Now, for raking in the changes;
|
|
|
|
git checkout master
|
|
git fetch upstream
|
|
git merge upstream/master
|
|
|
|
## Step 4.5 - Keeping your feature branch up-to-date
|
|
|
|
If you pulled in changes from `upstream` and did not yet share your feature branch, you can rebase your feature branch. This makes sure you have the latest code from `master`. This also makes merging your pull request easier.
|
|
|
|
<p class="important">Do <strong>not</strong> rebase if you already pushed your branch to Github. <a href="http://progit.org/book/ch3-6.html#the_perils_of_rebasing">Read why</a>.</p>
|
|
|
|
git checkout fix_for_this_or_that
|
|
git rebase master
|
|
|
|
If any conflict arise, fix them. And continue your rebase:
|
|
|
|
git add conflicting_file
|
|
git rebase --continue
|
|
|
|
You may also abort the rebase:
|
|
|
|
git rebase --abort
|
|
|
|
## Big picture
|
|
|
|
This small guide will help you to fork repositories on Github and use them to contribute code. By using the approach you lighten the task of the project maintainer who can easily checkout your specific changes and decide to include them into the main project or not. |