Howto setup a CiviCRM development environment for fixing bugs

The steps for proposing a fix consist first of setting up an environment for fixing bugs and proposing a Pull Request (PR).

There are two ways for setting up an environment for fixing bugs, one is a fully running CiviCRM development environment, which requires buildkit, composer etc… In this tutorial I will explain how you could fix a bug in the code base and return your fix back to the community.  Of course, you have to fully test your fix.

My local development environment consists on several concrete CiviCRM installations, which usually reflects a clients system.

Usually it is my client who discovers a bug and its usually me who will report the bug in the issue database and will fix it. When I have reported the bug I will fix the bug in the install of the client. This way I and the client can test the solutions. After the testing is done we want to commit the bugfix back to the community. That is what is discussed in this tutorial.

This tutorial assumes you have already created a ticket in the CiviCRM Issue database and probably discussed the proposed solution on the forum.

This tutorial also assumes you have some experience with git and github.

The CiviCRM Core repository consists of several branches. Each branch is for a major version. E.g. the LTS is in the branch 4.4. The master branch is the latest development which will probably result in the next major version. The first thing you have to do is determine in which version you fix have to occur.

Determining the version

When I fix a bug in the install of client, I note what I have fixed. Usually its only a few lines of code.  What I want to accomplish is that those lines of code are integrated in the next version of CiviCRM. In the issue database you could see what versions are affected by the bug and in what version it should be fixed.

Creating a fork

First you have to create a fork of the CiviCRM Core repository. You go to and you press the button (in the screenshot below in the right upper corner).

Fork from CiviCRM Core

Github will then ask where you want to fork this repository. My advice is to fork it to your personal github account.

After this you have a personal fork of the CiviCRM Core repository.  My personal CiviCRM Core repository could be found at

This is the repository where you would commit your bugfixes to.

Cloning your personal fork

Before you can submit bugfixes from your local development environment. You have to clone your personal CiviCRM Core fork.

$ cd /home/jaap/http  # that my personal dev directory
$ git clone # replace with your github url

After that you have the CiviCRM core repository on your local development environment.

Adding the upstream for retrieving the latest

After you have cloned your personal CiviCRM Core fork. You want also retrieve the latest changes in the CiviCRM Core repository.  This what is usually called upstream.

$ cd civicrm-core
$ git remote add upstream

To retrieve the latest changes in the 4.4 branch you could use the following command

$ git pull upstream 4.4 # this will pul the 4.4 branch from the civicrm core
$ git push origin 4.4 # this will push the latest 4.4 branch to your personal github fork

Fixing and commit your bug

To fix and commit your bug your should first retrieve the latest from upstream (civicrm core repository). Create a branch which will contain only this particular fix.  In the example below we will fix something in the 4.4 branch

$ git pull upstream 4.4
$ git checkout 4.4
$ git checkout -b CRM-12345 # The CRM-12345 is your issue number and the branch for the fix
.. # Edit the files
$ git add .
$ git commit -m "Fixed #CRM-12345: changed typo in readme"
$ git push origin CRM-12345 # This will push your CRM-12345 branch to your personal fork

Create a pull request

After you have pushed your bugfix branch to your personal fork of CiviCRM Core you could create a pull request.

Go to github webpage e.g.: Select your issue branch from the branch drop down

select branch

Create a PULL Request by pressing the green button

create PR

The select the branch you want to merge to. Which is should match the branch on which your fix is based. E.g. in our example it is the 4.4 branch.

Screenshot from 2015-08-25 10-22-25

Add a message and click on create pull request. That is it. It is now time for the core team to merge your fix into the right branch of civicrm core.