Tuesday, 18 September 2012

In my previous post I wrote about setting up Eclipse, EGit and a GitHub account.

Today it is time to participate in an opensource project which is hosted at GitHub: Wicketstuff. It is hosted under https://github.com/wicketstuff/core

NOTE: The following cites the description found here and adapts it to our example of working with EGit on Wicketstuff.

The main repository (also called the upstream branch) is "wicketstuff/core". The maintainers of this repository are responsible of merging in contributor's commits.

Contributor's Workflow

Getting Started

Overview

  • Fork project
  • Install tools like git itself or EGit as Eclipse-plugin (if not yet done)
  • Clone repository
  • Start coding ;)
  • Commit early and commit often
  • Ignore the Github Fork Queue

Fork

Say you want to start contributing to the Wicketstuff project on github now. The first thing to do is to fork it on github. Forking is the preferred way of collaboration on github and it works quite well with git. Just follow the instructions on github.

In short: login and click "Fork" on the upper right corner on the "wicketstuff/core" project page.

Now you should have your own public repository which contains exactly the same history as the main repository at the time you forked. You will later push your contributions into this repository and the maintainers of the main repository will pull your commits into the main branch.

Clone

By cloning your fork on github you create your private local repository on your development workstation. You will mostly work with it and only publish changes to github when you feel they should be merged into the main repository.

Change into the Eclipse-Workspace-directory where you want the code to reside and then:
git clone git@github.com:YOURGITNAME/core.git
With the EGit-Plugin you can do the same by:
  • "File - Import - Git - Projects from Git - URI"
    • URI: https://git@github.com/YOURGITNAME/core.git
    • Host: github.com
    • Repository path: YOURGITNAME/core.git
    • Protocol: https
    • User: YOURGITNAME
    • Password: xxxx
    • Store in Secure Store
  • Select Branches: standard is "master" branch (or all if you are not sure)
  • Local Destination:
    • Directory: directory you want the code to reside
    • Initial branch: master
    • Clone Submodules: yes
    • Remote name: origin

Of course this only works if you managed to create an SSH key and successfully uploaded it to github. I will not go into details on this, because it is already documented very well on github itself. If you experienced any problems with this step tell me and I will put them here.
Now you got a git repository called "core" and are ready to start coding!