How to contribute to ZF2

... for git dummies

I'd like to show you how to contribute to Zend Framework 2. I'll focus on the technical issues you may encouter on the way. I assume you have set up GitHub correctly. If  not, consult GitHub help.

ZF2 is developed using GitHub and in contrast to ZF1, you don't need to sign CLA.

First step to contributong is creating your own fork (where you will push your changes and make pullrequests from). Go to https://github.com/zendframework/zf2 and choose "Fork" in the top left corner. That will create a copy of ZF2 repo in your account - for me, it's https://github.com/tomasfejfar/zf2.

Now clone the repo using

git clone https://github.com/tomasfejfar/zf2

Now you have the repo locally. It has two branches master and origin/master. Master is your local main branch. Origin/master is your fork's main branch. You need a way to communicate with the ZF2 official repo. So you need to add one more remote.

git remote add upstream  https://github.com/zendframework/zf2

Now you should have two remotes. Verify it using

git remote

You should see origin and upstream. If it's so - it's great. Remember it's generally a not a good idea TO COMMIT INTO MASTER. It will save you lot of problems and merge conflicts.

How to create a pullrequest

To contribute, you need to create a pullrequest. The pullrequest should ideally contain one branch. That branch should be branched from the most current master and it should contain ONLY the changes that are relevant to the pullrequest. If you are fixing two separate issues, create two separate pullrequests.

So, let's start. First you need to make sure your master is up to date. You may need to call

git stash

if you have some uncommited changes to clean your working copy. Don't worry, you may later return stashed changes using

git stash pop

When your working copy is clean, it's time to sync your repo with official zf2 repo (upstream).

git checkout master

git pull upstream master

git push origin

First, you checkout your master, than pull changes from official ZF2 repo and then push those changes to your fork. Now your master is in the same exact state as is the official zf2 master and so is your origin/master. And you may create a branch.

git checkout -b fix-something master

You are now on your local fix-something branch and you may commit as you wish. It's good idea to write descriptive commit messages (what is changed, what you tried to do), so that it's clear what your intentions are. When your changes are ready, you need to push that branch into your origin

git push origin fix-something

Now when your branch is on github, you go to your fork and there is a button "Pullrequest" on the top (or there may appear a message "you recently pushed branch fix-something, do you want to create a PR?". Yes, you do! From yourname/zf2 - fix-something branch to zendframework/zf2 - master.Note:  To be honest, I'm not sure whether you should pullrequest against master or develop. There are currently PRs for both and I can't find the pattern :) Important things are - create a branch for your PR and create that branch from recent master, not some two year old commit.

I hope this helps you to contribute to ZF2! For some more ideas about contributing to ZF2 read MWOP's blogpost (it's little outdated, but still have some important information). Documentation needs your help too. When in doubt, use the mailing list or ask on IRC.

Feel free to suggest improvements to this howto in comments or by sending me a mail ;)

This work is licensed under a Creative Commons Attribution 3.0 Unported License.