In the spirit of this Friday's Eclipse BugDay , I thought I'd put together a special on how to contribute to Eclipse for those that haven't done it before. We'll look at how to find a bug, how to fix and test it, creating a patch and then submitting it to Eclipse. You can see the previous instalment of the Getting started series if you want

These instructions have been written with the assumption of Eclipse Europa installed, along with the JDT and PDE. If you downloaded the "Eclipse for RCP/Plug-in Developers" bundle then you'll have both of these; if you downloaded the "Eclipse IDE for Java Developers" then it's possible that you don't have PDE installed. (There's a comparison of which includes PDE here if you're interested).

If you haven't got PDE installed, a quick trip to the update manager (Help -> Software Updates -> Find and install -> Search for new features -> Europa discovery site -> Java development -> Eclipse Plug-In Development Environment) should allow you to download PDE into your workspace.

Firstly, you'll need to find out what to contribute towards. You can use this link , or go to bugs.eclipse.org and search for bugs with the bugday keyword. These are bugs that have been specifically chosen for people to fix potentially easily, although you're more than welcome to dive outside those and look at the helpwanted keyword or even create your own.

If you like living with the latest technology then be sure to install Mylyn. You can then do Window -> Show View -> Other -> Mylyn -> Task Repositories, which will give up a view with "local tasks" and "eclipse.org" -- right-clicking on the latter and doing 'New Query' will give you a dialog box that you can choose to create a new query from a URL, such as the one above. You can then view the bugday tasks from the Window -> Show View -> Other -> Mylyn -> Task List, update the bugs and even see incoming notifications. Whilst it's the easiest way, you can still work with the web-based interface if you prefer.

Once you've got an idea to work on, let people know. You can do that in one of two ways; comment on the bug, or join in on the irc://irc.freenode.net/#eclipse-bugs channel that's been specifically set up to discuss bugday related code (or both). You can add IRC via ECF if you've got it installed (in the "Communications" category of Update Manager if you haven't) -- switch to the Communications perspective and click on the small arrow next to the icon on the toolbar. You'll get a drop-down list including IRC, MSN, BitTorrent, XMPPS etc. but choose IRC and enter something like me at irc dot freenode dot net/eclipse-bugs to join the conference. Unfortunately, it doesn't work behind firewalls or proxies.

So, you've found a bug, told people you're interested, and want to start work. Feel free to ask questions via the bugs (or IRC) -- the teams are likely to be quite responsive to new questions during the day, though you should also take into account that a number of them will be based in North America and so should take timezones into account, so replies might not be forthcoming in the morning where you are.

You'll obviously need the source. Eclipse hosts the source for all its code via CVS (well, the majority anyway) but has several CVSRoots. You'll need to know which one is used for the project in question; the CVS Howto contains a mapping for the projects and their locations.

Let's say we need to fix something in ECF. You can browse the ViewCVS to see if you can find any sign of the ECF code; but you won't find it there. Instead, there's a drop-down box with "Repository" next to it that currently has "Eclipse_Repository" selected. Change it to "Technology_Repository" and you'll get this view instead, which does contain an 'ecf' project. How did I find out? Well, there's about 6 to try, and you're likely to get it in the first three on average; also, when raising a bug you get the same mapping for project-to-repository:

BIRT - The BIRT Project
DataTools - The DataTools Platform Project
DSDP - The Device Software Development Platform
Eclipse - Eclipse SDK and Platform, SWT, RCP, JDT, PDE, Equinox
Eclipse Foundation - Community bugs (eclipse.org websites, eclipse.org CVS servers, bugs.eclipse.org, e-mail and other eclipse.org issues)
Modeling - EMF, GMF, GMT, JET, M2M, M2T, MDDi, MDT, UML2, XSD, and more
STP - The SOA Tools Platform Project
Technology - DLTK, ECF, EMFT, Higgins, Subversive and more
Tools - AJDT, AspectJ, CDT, GEF, Mylyn, Orbit, PDT, PTP, VE
TPTP - The Test & Performance Tools Platform
WebTools - The WebTools Project

It's not an exact mapping, but it can help to narrow your search a little.

OK, so having figured out that ECF is in Technology (which the " CVS Howto " lists as /cvsroot/technology ) we can set up our CVS client. Go to File -> Import -> Projects from CVS and put in :pserver:anonymous at dev dot eclipse dot org:/cvsroot/technology as a repository location (if you don't have it already). You can then navigate into the org.eclipse.ecf directory and check out some of the associated ECF plugins.

Note: I put together a plug-in to make this easier. Simply install this plug-in into your plugins directory, restart Eclipse, and then go to PDE's plug-ins view. Highlight the plug-in(s) that you want, and then click on the icon. In most cases, it will check out the HEAD for you straight into your workspace.

If you don't know what plug-in you are trying to fix, what do you do? Well, one thing is to ask for help; the people at the other end are likely to know. Otherwise, you can import many plugins and use Eclipse's search capabilities to find particular strings of interest. There's no easy answer here, but generally speaking plug-ins are broken down into 'ui' and 'non-ui' variants, such as org.eclipse.ecf.ui and org.eclipse.ecf . Normally, the actions on the menu are in the UI plug-in.

In addition, learning the mapping between text strings and the code is useful; because Eclipse is internationalised, the text strings are translated. They usually live in a plugin.properties (at the top level) or org/eclipse/foo/FooMessage.properties somewhere below. (If you've got WinZip, you can quickly find out files of type PROPERTIES from a bundle by opening it up in WinZip and sorting on the file type.) This normally corresponds with an NLS or Messages class in the same package/directory which will contain a 1-1 mapping between static fields and the keys in the properties file. So a property helloworld=Hello, world! will map to Messages.helloworld in the code. You can then find out (using References -> Workspace) all places in the code that refer to that constant, and you'll be where the UI component is created with that message.

So, you've got your code checked out. Fixing the bug is now a case of coding, and I can't advise on how to fix each and every problem. Obviously the debugger is good for solving some kinds of problems, and you can use that with Eclipse too. Understanding a few patterns (like IAdaptable ) is a bonus, as is familiarity with the toolkits like JFace and SWT.

On the assumption that you have made some changes, how do you test what you've got works? Well, the Launch can allow you to test an Eclipse application. Go to the Run menu (visible from the Java Browsing, Java or Debug perspectives, but not the Resource perspective) and do Open Run Dialog. You can then create a new Eclipse Application launch by clicking ono the 'new' button at the top-left when the Eclipse Application is selected. You can choose either to run a product (org.eclipse.sdk.ide) or an application (org.eclipse.ui.ide.workbench); both are the same as far as we're concerned. The plug-ins tab shows what will be selected; by default, that will contain the set of plug-ins in your workspace combined with the ordinary Eclipse install.

I'd recommend cleaning the workspace before launching (main tab), as well as the configuration area (configuration tab). There are some weird caching issues that can occur when you're making changes to the manifest/plugin.xml, and having a clean slate to start with is a good way of ensuring not being tripped up by these situations.

Once you've got your launch configuration, click Run to launch it. (You can also launch it in Debug mode if you want.) This should bring up a second copy of Eclipse, with your changes in place, which you can then manually test. You can then cycle through a develop/debug cycle as appropriate. If you're running in Debug mode, you can even change some parts of your code on the fly e.g. to fix NPEs. To be honest, I often run things in debug mode even when I don't plan on debugging, because it doesn't make that much difference to the launch time and it's then handy to decide I want to trap a breakpoint or a thrown exception during testing.

Some plug-ins have automated test plug-in(s), too. For example, ECF's tests are located here . Generally, to run a test, you have the source for the test plugin in the workspace in much the same way that you have the other code, and instead of launching it as an Eclipse application, you launch it as a JUnit Plug-in Test instead. What this does is to fire up an Eclipse instance, run JUnit internally on those tests, and then quit and report the test results to you. I doubt whether the bugday bugs will need that, but the committers at the other end are likely to be able to run the tests on your behalf if you can't figure out how to.

OK, so we've made the fix, tested, it, and it looks good. How do we get it into the Eclipse repository?

If you right-click on the project (and it's been checked out from the CVS source), you can do 'Team -> Create Patch'. This will generate a patch of the changes that you've made and offer to store them in a clipboard or file. I personally prefer saving it as a file (if only so I can look to make sure I've changed what I think I should have changed) and then attaching it later, although I believe that Mylyn will allow you to take the change from the clipboard directly. A change file looks like ordinary source, but wiht lines beginning with + where you've added (or modified) a line, and - where the original line was removed. A change to a simple 'Hello world' might look like:

@@ -1,5 +1,5 @@
 public class Test {
   public static void main(String args[]) {
-    System.out.println("Hello wurld");
+    System.out.println("Hello world");
   }
 }

In this case, we've just corrected the spelling of 'world' -- the line with the typo has been deleted, and the line without the typo has been added.

Your patch file (normally ending in .patch, by the way) can then be attached to the bugzilla report. If you've got Mylyn installed, this is a breeze; click on the 'create attachment' button. If you're going via the web interface, you can also click on 'create attachment' -- when it asks what type it is, make sure that the type is set to 'patch' so that it's recognised by the system.

You've now got your first patch into bugzilla; hopefully, at some point later the patch will be committed (although it's fairly common for someone to come back and ask you to make small changes to the way that it worked) and in the fullness of time, your code will live on in Eclipse Ganymede, coming to a 2008 near you ...

Alex.

PS You might also find Philippe and John's talk on contributing to Eclipse from EclipseCon06 useful reading material. There's also a wealth of information available in the Eclipse Faqs .