Fixing Bugs and Making Patches

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:

a detailed bug report
a patch file
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

Does an issue for your patch exist already?

We need some context and explanations for your patch, so that is where issue tracker comes in handy. If an issue doesn't yet exist, before you submit a patch you should create an issue on the issue tracker (create an account if you don't have one), if a relevant issue for your patch doesn't already exist. The CiviCRM issue tracker allows your patch(es) to be sorted by the CiviCRM team, tested, approved, and applied to the appropriate version.

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. This is a *nix command, so if you are using a Windows machine you can install CYGWin.

Navigate to the CiviCRM root directory (on Drupal, this is usually sites/all/modules/civicrm) and use the following command:

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

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

For more on creating patches from the command line, various guides are available on the web.

There are GUI interfaces to create patches, if you prefer. For Windows environments you could use WinMerge and for Mac try Apple's XCode.

There are cleverer techniques that you can use to generate patches if you are using version control systems, like SVN, or SVN GUI interfaces such as Versions or Tortise.

Applying patches

If you have found a patch on the issue tracker or forums that you wish to apply to your own codebase, download the patch and open in an editor of your choice. Patches are generally readable by humans as well as machines.

This screenshot shows how to use issue tracker to find patches

You should be able to decipher by looking at the patch:

1. what file(s) are affected

2. what line numbers are affected

3. what code has been removed (indicated by: - )

4. what code has been added (indicated by: + )

You can choose to apply the patch in one of the following ways:

1. By command line such as:

patch -p1 <  {/path/to/patch/file}

2. By using XCode, Versions, Tortise SVN, or other GUI tool

3. By hand (manual edit) if the code changes are relatively simple and brief

If you are having trouble there are many online tutorials for handling patches, just search for them.

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.

You can use SVN from the command line, or with GUI tools such as Versions or Tortise.

Adding tests to bug reports

Please test your patch before you submit in a variety of use cases, not just your own. For instance, if you are editing event registration payment code, check that your changes work not only for paid events but unpaid events as well.

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.

EDIT