Setting up your workstation for Joomla! development

From Joomla! Documentation

Revision as of 15:46, 16 September 2012 by Garyamort (Talk | contribs)


This article provides detailed instructions for setting up your workstation for Joomla! development with Apache, PHP, xdebug, Subversion. Please refer to the following links for other development tools and environments: Setting up your workstation for joomla development

The article more specifically let's you contribute to the official SVN Joomla! code.

The examples used and screenshots are for Windows XP, but the basic steps are the same for Linux.

Install & configure XAMPP, php, Eclipse

  1. Configuring a XAMPP server for joomla development
  2. Edit PHP.INI File for XDebug
  3. Configuring Eclipse for joomla development
  4. Git for Testers and Trackers
  5. Working with git and github/My first pull request

Check Out and modify Joomla! Source Code

Now we are going to create a new PHP project that will contain all of the source code files for Joomla!. We can import the source code and create our PHP project at the same time.

To do so, please see Working with git and github/My first pull request

Working With Patches

Bug fixes are normally created and tested using patch files. Patch files are plain-text files that tell Subversion how to change one or more source code files to reflect the changes included in the bug fix. A simple patch can be a small change to one file. A large patch might have major changes to multiple files. You can read more about patch files in the article Learn more about patch files.

Note that JBS (Joomla! Bug Squad) members do not normally commit changes to the Joomla! SVN. Our job is done when the patch is tested successfully and the issue is change to "Ready to Commit" status. Committing the changes to the Joomla! codebase is done by Ian, Kevin, or a member of the Development Team.

The normal work process for testing a bug fix is as follows:

  1. Update your local Joomla! to the latest from the repository. To do this, right-click on the project and select Team / Update.
  2. Normally, you will want to test the issue before applying any patch, to make sure you can duplicate the problem.
  3. Download the patch file from the tracker and apply the patch. The url is and choose the Joomla! 1.6.x Issue Tracker link.
  4. Re-test to see if the patch corrects the problem.
  5. Update the tracker with your results.
  6. Revert the programming changes so that your local SVN repository stays in synch with Joomla!.

How to Apply a Patch

To apply a patch file created by someone else, here are the steps:

1. Download the patch to your local computer (for example from the Joomla! Tracker).

2. Select the project in the PHP Explorer, right-click, and select Team / Apply Patch. The dialog shown below will display:

Apply patch1.png

3. Browse to the desired patch file and press the Next button. The screen will display as shown below:

Apply patch2.png

4. Select the target project where you want to apply the patch. Note that patches should normally be created with the project as the Patch Root. Press Next to display the Review Patch screen shown below:

Apply patch3.png

5. This screen shows you the file or files that will be modified by this patch. If you like, you can double-click on the file name to open the Eclipse compare window for the file. This shows you exactly what the changes to each file will be, as shown below.

Apply patch4.png

6. Press the Finish button to apply the patch. Notice the black "*" symbols in the PHP Explorer, as shown below. These show the files and folders that were modified by the patch and, therefore, are now different than the base SVN repository.

Apply patch5.png

Revert Changes

When you are done testing a patch, normally you will want to undo the patch so your local code base stays in synch with the Joomla! SVN. In Eclipse, you can undo patches in two ways: either revert changes or apply a patch in reverse.

Revert Changes

You can change a file or group of files back to the original state by using the SVN Revert command. In Eclipse, you just highlight the file or folder, right-click, and select Team / Revert. If you have selected one file, this file will be changed back to the version in the SVN repository. If you have selected a folder or project, then all of the files in this folder or project will be reverted. In this case, Eclipse will show a dialog listing all of the files to be reverted. You can then pick which ones you want to revert or cancel the operation.

Reverse a Patch

You can also use Eclipse to undo a patch. Follow the same procedure as for applying a patch. When you get to Review Patch screen, Eclipse will show an error, as shown below. Because the file has already been patched, the starting point of the file does not match what is in the patch file.

Reverse patch1.png

If you click on the box "Reverse Patch", as shown below, the error disappears, indicating that the patch will be reversed.

Reverse patch.png

Press the Finish button to complete the process. If you have only applied one patch file to the SVN, then reversing the patch is the same as just reverting the files (Team / Revert). However, if you are working with more than one patch file, the ability to reverse just one patch can be useful.


Error When Doing Team->Commit

When doing a commit, you get the message "svn: Server sent unexpected return value (501 Method Not Implemented)". This error can be caused by doing an anonymous checkout on a project that requires credentials to commit. The anonymous credentials are cached and so the commit is not authorized. To fix this, you need to clear the SVN cache. This can be done by removing the cache file. For XP, the file is c:\Documents and Settings\[username]\Application Data\subversion\auth\svn.simple. For Vista, it is c:\Users\[username]\AppData\Roaming\subversion\auth\svn.simple.
If you use Tortoise, you can right-click and select SVN->Settings->Saved Data and press the Clear button next to Authentication Data.

Extension Development

For Eclipse setup information related to Joomla! extension development, see Setting up your workstation for extension development.