Contributing to Flexmojos

WORK IN PROGRESS

This page is currently being created or overworked. Please don't treat it as a finished document.

I'd say there are 3 general types of people using Flexmojos.

  1. The Release-Guys that use the released versions in the flexmojos repository.
  2. The Bleeding-Edge Guys that build their own snapshots from source.
  3. The Edge-Cutters that keep the edge bleeding by contributing code.

If you belong to category 3 here comes a short description of the process in order to do so.

The big picture

At first I'll give you the "Big picture" ... at first everything seemed sort of "makes no sense" to me. My "Big Picture" was more of a "Pig Bicture" ;-)

There will be 3 Copies of the entire Flexmojos Git repository involved in the contribution process.

  1. The main Flexmojos Git repo, available via http from GitHub under the url https://github.com/Flexmojos/flexmojos
  2. Your local clone repository on your development machine (usually in the hidden ".git" sub-directories of your checked-out files)
  3. Your private fork at GitHub

And you also have the checked-out files in your filesystem (So in general you have every file 4-times).

Ok ... you might immagine why you need a local clone, but what is this private fork at GitHub for?
Well the reason is this: You can't commit to the trunk. Only Velo can do this (I think). So how can you submit patches? The naive CVS/SNV way would be to send a patch via Email. 
Ok well you can immagine that this really sucks ;-)
What happens here is that you commit to a publically accessible repository clone on GitHub that only you can commit to and then issue a "Pull Request" to Velo. He can now review your changes and pull these changes from your private fork at GitHub. If he likes what you did, he will apply your patches to the trunk and you're done.
As soon as you update your local repository with changes of the flexmojos trunk, Git will notice that some of the patches fetched have allready been applied and will skip them (Every patch has a unique id). 
This final step hopefully closed the loop and at least you understood the concept.

Setup your GitHub account and create your own fork

This step relates to Step 1 of the Big-Picture.

At first you have to register at GitHub (https://github.com/) As you will be working on an Open-Source Project the registration is for free.

Go to the Flexmojos project site on GitHub (https://github.com/Flexmojos/flexmojos) and login if you are not logged in.

In the upper right (under the search box) there should be a button labled "Fork" ... click on it.

What happens now, is that on GitHub your own private clone of the Flexmojos repository is created. This takes a few seconds and then you're ready to go.

Create your Private-/Public Key pair and register this at your GitHub account

// TODO ... DOCUMENT !!!

Setup Git on your development machine and fetch your fork from GitHub

I installed Git from here (http://git-scm.com/). After installing the basic Git stuff I additionally installed TortoiseGit (http://code.google.com/p/tortoisegit/) But this is just because I like to click more than I like to "commandline" ;-)

As soon as you have git Installed. Go to any directory where you want to ceckout flexmojos.

Now rightclick on a directory and select "Git Bash Here". A commandline window opens.

git clone git@github.com:{yourgithubusername}/flexmojos

The above command actually copies your private fork from github to a ".git" directory inside your checkout directory (Relates to 2 in the Big Picture). After this is done it copies the code in this local repository-copy to your file-system (Relates to 3 in the Big Picture), so you can edit it.

Now you are ready to start modifying your code.

Committing to your changes

As soon as you have finished your work and want to commit it, you have to first commit to your local git-clone of your remote private fork.
At first you have to commit your changes. This merges your changes into your local Git repository on your development machine (Step 1).
Unfortunately your changes still havent left your machine. In order to play the changes back to your GitHub fork you have to push them back (Step 2).
In order to do this you use the "git push" command:

git push origin flexmojos-4.x

As soon as this was successfull you should see your changes in the GitHub web-interface for your fork.

Unfortunately your changes still aren't in the flexmojos trunk. In order to get them there Velo has to integrate them into the main flexmojos fork. This is done by issueing a Pull-Request on the Flexmojos website. What happens now, is that Velo get's notified that someone has contributed stuff (Step 3) and he can review your changes in your fork (Step 4 + 5). If he likes what you did he will apply the patch(es) to the trunk and from now on they will be available to all (Step 6).

Updating your private fork

As you are propably not the only one contributing, the trunk of flexmojos will start to differ from your fork. So how can you keep up to date? When looking around on the GitHub page you will propably notice the "Fork Queue" where GitHub will show you what patches other forks of flexmojos provide. One of these forks is the flexmojos trunk "Flexmojos / flexmojos". Just a comment on the "Fork Queue" ... forgett about it. It seems that seems to have never worked. A lot of patches are shown "red" even if there should be no reason for it to be red. In order to update your fork you have to update the repository clone on your development machine and then push those changes back up to GitHub. It took me quite some time to figgure that out ;-)

Now to how you do that:

At first you have to configure a so-called "remote". You can think of this as a brother/sister repository that should contain the same project. Do this by issueing the following commands in the "Git Bash". You only have to do this once ... it creates an alias called "upstream" to the main repository. After creatig that alias you can use it in followin sessions without having to redefine it.

git remote add upstream http://github.com/Flexmojos/flexmojos.git

From now on you can address the main flexmojos fork with the symbolic name "upstream".
As soon as this is setup you can fetch changes from the "upstream" repository. (Step 1)

git fetch upstream

Now the changes are in your local Git repository, but have not been applied to you local checkout. To apply the changes to your code a final step is needed: (Step 2)

git merge upstream/flexmojos-4.x

Which merges the latest changes of the flexmojos-4.x branch to your locally checked out project.
After the code is merged, you can push it back to you private fork (Step 3)

git push