Saturday, November 15, 2014

Contributing on Github

This is one of those things I end up doing now for the third time, and since it is not something I do pretty often, I always forget the steps since I don’t work with git on my day to day job. Also, as Scott Hanselman suggested some time ago, you should write a post for future reference, chances are it will also eventually help others.
So here it is, this is my step by step guide on how to contribute on a Github repository (actually any git repository) you don’t own. When you own it, it’s obviously simpler, we’ll see that part too, but when you don’t own it and don’t have enough privileges to push your changes to your repository, you need to create a pull request.
Little disclaimer: I’m not a git wiz or anything, I’m just annotating the steps that I found that worked for me for what I wanted to do. If there is a “better” option or you see anything that should be done differently, don’t hesitate to leave a comment.

Fork it

So, if you want to pull a request, you have to have a repository to pull from. To do that go to the upper right corner of the repository page and hit the fork button (I assume you already have a github account).
fork

Clone it

Ok, you have your “own copy” of the repository, but where? yeap, up in the sky. You now want to bring the sources to your hard drive. To do that you need to clone the repository. In order to clone it you need first to know the clone address, you’ll find that address again in your repository fork page under HTTPS clone url (clever, uh?)
So, open a command line, yes a command line, the command line is your friend, go to the directory where you want the source code to go and type:

git clone
 
After that you’ll see some magic. If it’s the first time you’ll be asked for credentials.

Do some work and commit the changes

After the transfer is done, you have your own local copy, of your own repository in your hard drive, now we can start changing what we want.
Always remember git status, git status is also your friend and it is the one that will tell you what’s going on. If you run git status right after the clone, you’ll get a message saying everything is up to date. But if you do run it after you modified a file, you’d get a message saying there are some changes but it’s not being tracked, which means it will not be committed, so you’ll need to add the files to what’s called as stage.
To do that type:
git add –a
 
If you run git status now you’ll see everything is ready for commit, so, let’s commit that.
git commit –m “your commit comment goes here”
 

Push it

Now you need to push the commit to the server, in this case, the forked repository. If you come from non-distributed version control systems and don’t know why is there a commit and a push I suggest you go read a little bit about git and distributed version control systems. Also, there’s a pretty good hand-on lab tutorial that helped me start with git (Try Git).

git push
 

Pull request

Now go to the original repository and create a pull request. You’ll see that you’ll be able to see you own repository commit where you’ll create the pull request.
And that’s it, you just created a pull request and hopefully it’ll be accepted and merged into the original repository.

Remote add

That’s it? well, not exactly. Chances are, you’ll want to keep your copy of the repository up to date so you can continue contributing. In order to do that you need to add another remote repository to your local copy. This remote will be linked to the original repository you forked from.
So type:

git remote add
 

Keep your copy up-to-date

You need to update your local copy from the original repository, the one that changed, since I’m the only one working on my own fork.

git pull master
 

Again, push

Keep in mind you just pulled the changes from the original repository, this changes are not in your own forked repository, so you need to push those to your fork.

git push origin master
 
 
And that’s pretty much all you have to do. Keep in mind you’ll be iterating thru pulling from the original repository, adding your changes, committing and pushes your changes and creating pull requests to the original repository.
The following diagram pretends to show you a “big” picture about the procedure.

git

As mentioned before, I’m not a git wiz or anything like it so if anything goes wrong, you’re pretty much on your own. Because as a common statement of this blog, this is 100% “works on my machine” certified.

workonmymachone

No comments: