Get Involved in the Debug Project

Overview

There are many ways that you as a member of the community can get involved and contribute to the Debug Project (either Platform or JDT Debug).

The first step is to let us know you are out there. Sign up for our mailing lists and chat with us about your problems and interests. You should also sign up for a Bugzilla account and add jdt-debug-index@eclipse.org and platform-debug-inbox@eclipse.org to your watch list.

Here are some ways you can contribute:

  1. Participate in Bug Day.
  2. Write code, developing source artifacts and patches for the debug projects.
  3. File bug reports in Bugzilla for defects you find.
  4. Participate in a milestone test pass.
  5. Assist in bug triage by checking if reports are duplicates, out of date, missing fields, etc. Read up on filing bugs and then take a peek at our Inbox.

Mailing Lists

There are two developer mailing lists for debug, one for Platform and one for JDT. Once you have signed up you will have permission to post to the list and let us know who you are and how you want to get involved.

Writing Code for the Debug Components

All development on the Debug Platform is done using Eclipse. Code is checked out of the Eclipse CVS repository, edited using JDT, and then run by launching a second instance of Eclipse from within Eclipse.

Note that any contributed code must follow the coding guidelines outlined on dev.eclipse.org. When working on debug code, you should set your compiler compliance level to 1.4 (Java > Compiler Preference Page).

Your first step is to download an Eclipse build. You can download a the Eclipse platform at here. New users are best off downloading the latest stream stable build. Once you have the platform downloaded, setup and launched, you can connect to the CVS repository.

Connect to the Eclipse Repository

The easiest way to download the correct projects from CVS is to use our Debug Project Set File. Download the psf file for non-committers then in Eclipse go to File > Import and select Team > Team Project Set. If you have not done so already, you will have to define a repository connection which can be done using the information below. The project set file will checkout the debug projects from CVS. More information about project set files can be found on the PSF Wiki Page.

Create a CVS Repository Location with the following information:

Attribute Name Value
Host: dev.eclipse.org
Repository Path: /cvsroot/eclipse
User: anonymous
Password: (blank)
Connection Type: pserver
Use Default Port: ON (default)

You can check projects out of the HEAD stream of the newly created repository location by selecting them, then Right Click > Check Out. Check out the Debug projects:

  • org.eclipse.core.variables
  • org.eclipse.debug.core
  • org.eclipse.debug.ui
  • org.eclipse.jdt.debug
  • org.eclipse.jdt.debug.tests
  • org.eclipse.jdt.debug.ui
  • org.eclipse.jdt.launching
  • org.eclipse.test.performance
  • org.eclipse.test.performance.win32
  • org.eclipse.ui.console

Your workspace setup is now complete. The Debug Platform projects are set up to compile against your installed Eclipse plug-ins (the plug-ins that are being used by your currently running instance of Eclipse). This works because the Debug Platform projects have the "Plug-in Dependencies" library on their Java build path.

When you upgrade your Eclipse install, the Debug Platform projects will automatically compile against the new plugins. To compile against a different set of plug-ins, you can change the location in the preferences under Window > Preferences > Plug-in Development > Target Platform.

Import Required Plug-ins

NOTE: You can probably skip this section. If you are compiling other projects that don't use the "Plug-in Dependencies" library, you may need to import required plug-ins manually, as explained here. Otherwise, this step is not necessary.

Import required plug-ins using the "External Plug-ins and Fragments" import wizard. The default values will import binary plugins from your host install. This is generally the right thing to do. On the plug-in selection page, import all plug-ins and select "No to All" when prompted to overwrite the plug-ins that are checked out of CVS.

If you import binary plug-ins this way, you'll need to reimport them manually every time you want to compile against a new version of Eclipse (as when a new Integration build occurs).

Launching the Run-time Workbench

Once your workspace is set up, it's time to launch Eclipse from within Eclipse. To do this, select Debug As (or Run As) > Run-time Workbench from the Debug (or Run) menu. This will launch a second instance of Eclipse (which we refer to as the "target") running the code in your workspace.

Any changes you make in your first workspace (which we refer to as the "host") will be reflected in the target. Test changes made in your host workspace by running and debugging programs in the target.

Creating Patches

So now you have the code to fix a bug in your host workspace and have tested it in your target. The next step is to get that code committed to CVS. However, only committers have the permission to do that. Instead, contributors are expected to create a patch file containing their changes and post it to the bug report they are working on. The patch will be reviewed by one or more committers. Once the patch is accepted, a committer will apply it to CVS and resolve the bug as fixed.

To create a patch, select all of the changed projects in the Package Explorer view. Right click and go to Team > Synchronize, this should open up the Synchronize View. In the Synchronize View, make sure there are no conflicting changes and that all of your changes follow the coding guidelines. Then select your outgoing changes, right click and go to Create Patch... In the dialog, select a destination for the patch (it is best to include the bug number in the file name and use the extension .patch), double check all your changes are included, then hit OK. Attach the created patch to the bug report.

Creating Bug Reports

When filing bugs against the Debug Project, we ask that you use your better judgment, and most importantly common sense before filing a bug. Specifically:

  • Search bugzilla for existing bugs like yours BEFORE you file it. Resolving duplicates is time consuming.
  • Be sure that what happened is really a bug. For example if all you see is an entry in the log files that mentions debug (platform or otherwise) try to reproduce it, find out how it happened, or better yet come up with a test case. Some log entries are NOT bugs, and can be caused by incorrect workspace configuration, etc.
  • Bugzilla is not a forum. Do not ask questions on bugzilla like "how do I create a launch configuration?". This is not a bug.

Bugs that apply to the Debug Platform (breakpoints, debug views, and launch configurations), should be filed against the PLATFORM-DEBUG component. New feature requests should be filed with a severity of "enhancement". Similarly, those bugs that apply to JDT Debug should be filed against the JDT-DEBUG component.

By default, bugs filed against a Debug component will be assigned to an inbox account. Interested parties watch this inbox user to see incoming bugs. Committers or the Debug team lead move bugs from the inbox account when someone is actively working on a bug.

Bug Lifecycle

All bugs for either the JDT or Platform Debug component follow the same lifecycle. All committers and contributors must adhere to this lifecycle to ensure all defects are tracked and handled accordingly.

  • NEW - All newly filed bugs start out in the NEW state.
  • DUPLICATE/INVALID/WORKSFORME/WONTFIX - If a bug is a duplicate of another bug or if a Debug committer decides that no code changes will be made for the bug, the bug is resolved immediately with an explanation. Unless the bug is REOPENED for some reason, this is the end of the road.
  • ASSIGNED - Once a bug has been validated by a Debug committer, it is moved to the ASSIGNED state. When a committer is going to work on a bug, they typically reassign it to themselves.
  • RESOLVED-FIXED - Bugs are marked as RESOLVED-FIXED once code that solves the issue has been checked into CVS. When requesting that someone verify a bug, we include a list of all affected files with a brief explanation of the changes. This makes the verifier's work easier and also provides valuable information if a change needs to be reviewed in the future.

    Bugzilla is picky about the state changes it allows, so we follow these steps to maximize efficiency:

    • Reassign the bug to the Debug committer who will be asked to verify the bug.
    • Copy the list of changed files from the Synchronize view and paste them into the comment section of the bug report. For each file, provide a brief description of why the file was changed.
    • Commit the code changes to CVS.
    • Mark the bug RESOLVED-FIXED with a request to verify.
  • VERIFIED-FIXED - Bugs are marked as VERIFIED-FIXED once someone verifies the fix that was checked into CVS. Bugs are always verified by a Debug committer other than the person who checked in the fix. The verifier makes sure that the original problem is fixed and also looks at the code for any obvious errors. This verification step ensures that all code changes are looked at by at least two pairs of eyes. In addition the verifier will add an entry in the build notes stating that the bug has been fixed.

Test Passes

Before every milestone release the Debug Team does an intense one-day test pass where we test all of the functionality of the debug components. We try to check everything to make sure 100% of the functionality is available in every major release. In addition, we try odd use cases and unusual code to ensure our code is as robust as possible.

To organize the test pass, we follow a test matrix. The matrix defines who is working on which platform (OS and VM combination) and who is responsible for testing what functionality. The matrix also contains a basic overview of what must be tested in each section.

NOTE: Testing should always be done on your host, so to launch Eclipse with a specific vm, you should launch Eclipse with the following argument: -vm C:\(JVM Location)\java.exe You can also use our example manual testing programs.

If you would like to help out during a test pass, contact us via our mailing lists. Before the test pass, let us know what platform you are going to test on and what sections you are planning to test. If you have any questions about how to test some area, we would be happy to help explain.