Zikula Network

Get in touch!
 
irc.oftc.net #zikula
 
Share your Knowledge!
 
Follow The Zikulan!
 
GitHub Core

Show your support for Zikula! Sign up at Github account and watch the Core project!




GitHub Modules

Subscribe!

How to Contribute Your Code at Github

You may be curious how you can contribute to the Zikula project or any of the module projects now that many of them have moved to Github. The good news is that it is actually pretty easy to do so. We just haven't done a good job of publicizing how it's done. Well, that is what this article is all about!


I use a graphical front-end client for my local Git install called SmartGit. This tool is free and available for Windows, MacOS and Linux. I know that there are many similar tools available and of course, you can also use the command line. (TortoiseGIT is a very popular tool for Windows). This article will focus on the command line. SmartGit can do all of this and I'm sure your preferred tool can do much of this as well.

So here's the situation: you would like to add a certain feature to the Zikula core and you can code it, but you do not have write access to the source code repository. Git is designed to make it easy to contribute your code to the project and GitHub is designed to make it easy for the project lead to integrate those contributions. Please note that this would also work for ANY GitHub project.

This tutorial assumes that you already have a working knowledge of git and GitHub.

Step 1 - Document Write a ticket at the project's tracker. Most projects in the Zikula world are hosted at the Cozi and the core is no different. It is important that your ticket is as descriptive as possible. In many projects you will be able to then immediately 'assign' the ticket to yourself, indicating to the project lead that you intend to contribute code. If not, you should attempt to contact the project lead to communicate your intentions. Once this is complete you will want to take note of the ticket number.

Step 2 - Fork Fork the project to your own GitHub account (I am assuming you already have an account). This only needs to be done ONCE per project. You're really not going to use your own fork per se, but it is important that you have this connection to the main project. You can accomplish this by going to the project's GitHub page and clicking the 'fork' button in the upper right corner of the page. After a few seconds, your fork will appear in your own account.

Step 3 - Clone Clone the *main project* to your local machine (NOT your fork!). This is also only done ONCE per project.

Code

  1. $ git clone git://github.com/zikula/core.git my.core.fork

This is telling your local git installation to create a repository with the source from git://github.com/zikula/core.git and give it a name called my.core.fork (you can choose a different name if you wish). Remember that the repository is created in the directory you are performing the command.

Step 4 - Add a Remote In order to push your changes somewhere where they can be found and pulled into the project, you need a new remote. This is because we cloned the main project and we don't have 'push' rights to that project (origin). A remote is a pointer toward an online repository (source). Go to your own fork of the project at GitHub and copy the SSH link for the project. It should look something like this: git@github.com:!username!/core.git. Then do the following:

Code

  1. $ cd my.core.fork
  2. $ git remote add my.core.fork git@github.com:<username>/core.git
  3. $ git remote

you should have a list of two two remotes: 'my.core.fork' (the pointer to your own forked repo at GitHub) and 'origin' (the pointer to the original project repo at GitHub).

Step 5 - Branch You should create a branch of your repository in which to make your changes. This is where you would need the ticket number you noted earlier (I'll use Ticket #1234).

Code

  1. $ git branch Ticket_1234
  2. $ git checkout Ticket_1234

Step 6 - Code & Test Now you can code all you like. All your changes are taking place in the Ticket_1234 branch and the master branch remains unchanged. You can use your favorite IDE in order to do your development. I recommend NetBeans but others use Eclipse or Aptana or others. Be sure to test all your changes and make sure you follow appropriate QA procedures for the project.

Step 7 - Commit This can actually be done multiple times if needed. When you have finished your coding for all or a part of your additions, commit your changes to your repository. Be sure your commit messages references the appropriate ticket number. (Commits can be done several ways. Therefore there is no example here).

Step 8 - Rebase Since the main project may have changed since you pulled your source. It is important that you 'rebase' your source code. This will bring your code up to date and alert you to any conflicts that may have occured between your code and the changes that may have been made.

Code

  1. (make sure you are in the correct branch)
  2. $ git checkout Ticket_1234
  3. $ git pull --rebase origin

If there are any conflicts, you will be notified. Resolving those conflicts is outside the scope of this tutorial. If this occurs, you will need to resolve all conflicts before continuing.

Step 9 - Push You now need to push your changes to a remote branch at your fork at GitHub so that they can be reviewed and possibly incorporated into the main project.

Code

  1. $ git push my.core.fork Ticket_1234

Step 10 - Issue Pull Request In your browser, navigate to your fork at GitHub and select the branch you want to 'send' to the project lead. Click the 'Pull Request' button in the upper right corner of the page. Describe your request and submit the form.

Step 11 - Keep Up To Date It is helpful to the project lead if you keep your ticket branch updated to the latest commits. This makes your branch easier to integrate when the project lead gets to it. Since this could be days or weeks, other commits to the main project may occur in between. To do so, simple rebase your local branch (step 8) and push the changes to your branch (step 9). This will keep your branch up to date.

Conclusion I hope that this quick tutorial will make it easier for you to contribute to the Zikula core project or any module that is part of Zikula. Contributions from many people make the project better and helps build the community. Of course, if you cannot code, you can still contribute in other ways. The biggest of which is testing and documentation. So get involved and help out!

References: http://www.kernel.org/pub/software/scm/git/docs/ http://help.github.com/ http://progit.org/book/ http://evgeny-goldin.com/wiki/Git


Share This | Print

Trackbacks

(The URL to TrackBack this entry is: http://blog.zikula.org/index.php?module=TrackBack&id=26,1-73). If your blog does not support Trackbacks you can manually add your trackback by using this form.
 
Close

You don't have permission to e-mail this story - please login