You've been exploring GitHub and have discovered a project you want to contribute to. Let's say it is my fork of the Functional Koans. You want to add some flair to the Python Koans in particular.
Fork the DocOnDev project
To create a fork, press the "fork" button on the project's page.
When the fork is complete, you will have a copy of the project in your repositories listing.
Clone your projectNow you need to clone your fork. Make sure you use the “Your Clone URL” and not the “Public Clone URL”. You want to be able to push changes back to your own repository.
$ git clone firstname.lastname@example.org:[your-github-account]/functional-koans.git
Once the clone is complete your repo will have a remote named “origin” that points to your fork on github. You will use "origin" for your own regular activities.
Get the sourceLet's make sure we have the python source.
$ cd functional-koans $ git checkout -b python $ git pull origin python From email@example.com:[your-github-account]/functional-koans * branch python -> FETCH_HEAD Auto-merging README.markdown CONFLICT (add/add): Merge conflict in README.markdown Automatic merge failed; fix conflicts and then commit the result.
Ugh. File conflict. No worries, open the file and edit it to look like this:
# Functional Koans ### About the Koans There are several functional languages that have contributed their own versions of the koans. Each language has it's own branch with detailed instructions on how to get started. ### Getting Started To get the koans for a particular language, simply clone the repo and checkout the branch: 'git clone git://github.com/relevance/functional-koans.git' 'git checkout branch -b [branch_name]' 'git pull origin [branch_name]' where [branch_name] is the name of the branch (language) you want to work on. To get a list of all branches run: 'git branch -a'
Now add the changed file to the python branch and check it in
$ git add README.markdown $ git commit -m'Fixed README conflict'
Add a remote to the original projectFirst, switch back to the master branch locally.
$ git checkout masterThen let's take a look at all of our branches.
$ git branch -a * master python origin/FSharp origin/HEAD origin/clojure origin/master origin/scalaWe see that the origin (your repository) has all of the branches, but our local repository only has master and python. The asterisk next to master indicates this is our active branch.
Let's add another remote that points to the source you originally forked from. You can call this remote anything you want. I suggest you use something that makes sense to you. In GitHub's examples, they use the name "upstream", but that I find that to be too general. I tend to name this remote after the original account I forked from. So for the sake of this example, we will use my convention:
$ git remote add DocOnDev git://github.com/DocOnDev/functional-koans.git
You may have noticed that we used the public clone URL for DocOnDev. Truth is, he probably won't give you access to push changes directly to his repository anyway. I heard he's a real jerk about that stuff. And if he had given you access to push directly to his repo, why did you create a fork...?
Just to be sure...Ok, so we just forked the code, but let's make sure we have the absolute latest version from DocOnDev before we start hacking away. We are going to fetch the latest from DocOnDev. Fetch grabs the latest source from all branches in DocOnDev's functional-koans repo and brings them down to us.
$ git fetch DocOnDev From git://github.com/DocOnDev/functional-koans * [new branch] FSharp -> DocOnDev/FSharp * [new branch] clojure -> DocOnDev/clojure * [new branch] master -> DocOnDev/master * [new branch] python -> DocOnDev/python * [new branch] scala -> DocOnDev/scala
Now if we take another look at the branches...
$ git branch -a * master python origin/FSharp origin/HEAD origin/clojure origin/master origin/python origin/scala DocOnDev/FSharp DocOnDev/clojure DocOnDev/master DocOnDev/python DocOnDev/scala
Make your changesYou are now free to make your changes and updates. You can add functionality, refactor, whatever it was that inspired you to contribute to this project in the first place.
Make sure you are cognizant of the various branches. Don't make changes in python branch, switch to master branch, and commit unless you absolutely intend to add the file to the master branch. Check in early and often. And of course, write your tests first. ;)
Check in every so often and fetch (or pull) any changes DocOnDev may have committed.
$ git checkout python $ git fetch DocOnDev python From git://github.com/DocOnDev/functional-koans * branch python -> FETCH_HEAD
Request a PullYou've completed your changes and you'd like DocOnDev to take a look at them and consider them for addition to the project. Simply navigate to your fork and use the "Pull Request" button. You can explain your changes to DocOnDev as a part of the request.
And that's the basics of it. It may take a while to get used to working on a project with multiple branches and multiple committers. I know I hozed my repo more than once before I got the hang of it.