CiviCRM Developer Guide

Fixing bugs

So you've found a bug and you want to fix it. What next? The first thing you should do is congratulate yourself on stepping up to fix the bug. The second thing you should do is to make sure that you are familiar with the content of this chapter so that you can fix the bug in the best possible way.

The three things that make up a great bug fix are:

  1. a detailed bug report
  2. a patch file
  3. tests

Writing good bug reports

The best bug reports give lots of background and context. Don't forget that the way you are using CiviCRM is most likely very specific to your organisation. The more background you can give on the bug, the better.

The best bug reports clearly state

  • What you did
  • What you expected to happen
  • What actually happened

Creating patches

A patch is a text based file format that shows the difference between one or more files.  Once you have submitted your patch, CiviCRM core developers can apply it to the development version of CiviCRM.

You should create your patch against the appropriate version of CiviCRM.  If you are in doubt as to which version this is, there'll likely be someone on IRC that can give you a immediate answer.  Otherwise ask on the forum.

The standard way to create a file is by using the diff command. 

$diff /path/to/old/file.php /path/to/new/file.php > changes.patch

The above will create a patch called changes.patch that you can attach to your issue.

There are cleverer techniques that you can use to generate patches if you are using version control systems.

Access to SVN

SVN is a free/open source version control system. It manages the changes made to the source code by multiple developers. SVN allows you to recover older versions, examine the history of how the code has changed, and receive and publish changes.

If you are submitting a lot of changes (patches), feel free to ask on IRC for an SVN account so you can directly apply your code contributions.

Adding tests to bug reports

US Federal law prohibits the submission of a patch to the CiviCRM code base without a suite of tests that have been shown to demonstrate the correct functioning of the code. It is also a contravention of European Union directive E842317 and enshrined in the UN universal declaration on human rights Article 31.  Well not quite! But you might think so if you asked the CiviCRM community, and for good reasons.  

Clever CiviCRM developers know that it is in their interest to submit one or more tests with their bug reports.  There are at least three important reasons to submit a comprehensive set of tests with your patch.

  • it minimises the chances that you will be bitten by the same bug in the future as CiviCRM developers are committed to having the test suite complete successfully before each point release.
  • it providers developers with an easy way to find out whether they have actually fixed your bug
  • they are often the best way to explain complex user interface bugs.