Jump to: navigation, search

Debug/Developers

Platform Debug
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse Source
JDT Debug
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse Source

Contributing to JDT or Platform Debug

Platform and JDT debug are driven by a small development group with limited resources. ANY serious developers or contributors will be enthusiastically welcomed. For more information on how to become a committer, check the standard Eclipse process (see New Committer Election). For more information about contributing to JDT or Platform Debug in general, or for questions about its internals, contact jdt-debug-dev@eclipse.org or platform-debug-dev@eclipse.org respectively.

Creating Bug Reports

When filing bugs against the JDT or Platform 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 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 HelloWorld class?". This is not a bug.
  • Bugs should be filed against the PLATFORM-DEBUG or the JDT-DEBUG component. New feature requests should be filed with a severity of "enhancement".
  • Understand what the different severities mean and choose accordingly. Setting a trivial bug to critical will not get it fixed any sooner (but will have its severity changed immediately).
  • Do not assign a bug to a committer unless they have already agreed to work on it.

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 one of the Debug team leads move bugs from the inbox account when someone is actively working on a bug.

Bug Summary Tags

When bugs are triaged a committer may add tags in square brackets to identify which feature the bug is related to, this helps when crafting bugzilla queries to find particular categories of bugs.

Some of the common tags currently being used are:

  • [breakpoints] breakpoint support
  • [console] console view support
  • [debug view] debug view (aka launch view) support
  • [evaluations] JDT evaluations
  • [launch]/[launching] launch configurations, delegates, UI, etc.
  • [patch] the bugzilla has a patch attached
  • [perspectives] perspective activation upon start of debugging
  • [source lookup] mapping debugger sources to the host file system, opening the editor
  • [var]/[variables] variables view support
  • [viewmgmt]/[View Management] Auto-opening of views in perspective upon stat of debugging.

Contributors are free to add any tags they feel will help with the discoverablility of the bug - within reason.

Make a Contribution

Before starting to develop an enhancement or fix for JDT or Platform Debug, it is important that you get in touch with the project. We track ideas for enhancements and bug reports in the Eclipse bugzilla (JDT Debug / Platform Debug), so this is a good place to present your ideas for a patch and to make sure it's going in the right direction.

If you want to do an enhancement but don't know where to start, you can also just ask on either jdt-debug-dev@eclipse.org or platform-debug-dev@eclipse.org.

Get the Source

JDT and Platform Debug are hosted in Git and can be viewed online: JDT Debug, Platform Debug.

To be able to make a fix or provide an enhancement, you will want to create an Eclipse workspace and import this source. The best resource for setting up a repository in Eclipse and importing project can be found on the EGit howto page.

Once your repository is set up in Eclipse the projects you want to import are:

org.eclipse.core.externaltools
org.eclipse.core.variables
org.eclipse.debug.core
org.eclipse.debug.examples.core
org.eclipse.debug.examples.ui
org.eclipse.debug.tests
org.eclipse.debug.ui
org.eclipse.jdt.debug
org.eclipse.jdt.debug.tests
org.eclipse.jdt.debug.ui
org.eclipse.jdt.launching
org.eclipse.jdt.launching.macosx
org.eclipse.jdt.launching.ui.macosx
org.eclipse.ui.console
org.eclipse.ui.externaltools

Your workspace setup is now complete. You do not have to import all of the dependencies for the debug bundles (unless you really want to) - those will be satisfied using the plug-ins running in or installed in the version of Eclipse you are using. Even when you upgrade your Eclipse install, the Debug projects will automatically compile against the new plugins.

It is good practice to develop the latest versions of the Debug plug-ins using the latest version of Eclipse. For example, as of this writing, Eclipse 4.4 would be used to develop Debug code from the master branch. The reason being that as the code evolves it might have changes that would not compile against an older version, which in turn would greatly complicate your workspace setup.

Coding Conventions

  • Follow the Eclipse Platform's Development Conventions and Guidelines.
  • Every file must contain a copyright header, as described in Development Conventions and Guidelines. The copyright header goes before the package declaration, starting in the very first line. For new files, list "yourself and others" instead of "IBM and others" in the first line. For changed files, add a contribution comment in the copyright header with your name and affiliation, and a bug id.

For instance:

/*******************************************************************************
* Copyright (c) 2008, 2014 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
* 
* Contributors:
*     IBM Corporation - initial API and implementation
*     John Doe <John.Doe@eclipse.org> - Bug 429728
*******************************************************************************/
  • JDT / Platform Debug comes preconfigured to use project-specific settings for compiler warnings/errors, code formatting etc. These settings must not be changed, unless the bug you are fixing is to propose a new default value for one of them.
  • It is considered good practice to write code that does not have warnings. If possible, fix warnings existing whenever you see them.
  • Non-externalized strings are considered errors, do not ship non-externalized strings or use the NON-NLS tag to indicate that you are not relevant for translation
  • Use unix line delimiters (In Eclipse select Window-> Properties -> Workspace and set the file delimiter to Unix
  • Write/update Javadoc for all classes / interfaces / methods / fields you introduce/change.

Creating Patches

So you have the code to fix a bug in your host workspace, have tested it in your target workspace and ensured all of the [#Unit_tests|JUnit tests pass]. The next step is to get that code committed to the git repository. JDT and Platform Debug accept contributions using patches attached to the corresponding bugzilla or Gerrit review requests (as we will discuss in the next section).

To create a patch, follow the simple steps on the EGit wiki. After you have successfully created the patch, have verified it contains all of the changes you would like to make, attach it to the bugzilla with a brief comment about what the changes it contains do. For bonus points you can edit the title of the bugzilla to start with '[patch]'.

In due time one of the project committers will review your patch and either apply it to the git repository or comment on the patch stating what is wrong and request changes.

Using Gerrit

Just like creating a patch, you have a code fix, have tested it in your target workspace and ensured all of the [#Unit_tests|JUnit tests pass], but you would rather not submit a patch. In that case you can use Gerrit. A great resource for getting started using Gerrit, is Lars Vogel's tutorial for contributing via Gerrit.

If you have not already done so, you will have to configure the repository you want to contribute back to to use Gerrit. Instructions for this configuration can be found on the EGit Gerrit set up wiki.

The JDT Debug Gerrit repositories are:

The Platform Debug Gerrit respositories are:

Once you have Gerrit configured for the debug repositories and are ready to commit your fix, make sure you read and follow the Commit Messages section before you commit / push your change.

Testing the Fix

Unit Tests

Both JDT and Platform Debug have JUnit tests that we use to help prevent regressions and other problems from creeping in from bug fixes. These tests must be run prior to submitting a patch or a gerrit request. The very first thing a commiter will do is run these tests, and if any fail your contribution will be immediately rejected.

Luckily though, there are shared test configurations that you can use to run these tests exactly as the committers do. They are found in:

  • org.eclipse.jdt.debug.tests
  • org.eclipse.debug.tests

To run these shared configurations simply open the launch configuration dialog, look under the JUnit Plug-in Test type to find the JDT Debug Test Suite and the Platform Debug Test Suite configurations.

Target Testing

After you've run the JUnit tests, you will want to see / debug how your fix behaves in Eclipse. The simplest way to do that is to launch what is called a target workspace and run through a bunch of manual testing.

To start a target workspace simply open the launch configuration dialog and create a new Eclipse Application launch configuration. You can customize where on disk the workspace will live, etc., but right out of the box the new configuration will launch a target Eclipse that will contain all of the changes from your workspace.

Host Testing

When you work on your fix the most common way to verify it is working is to run the JUnit tests and launch a target workspace. Sometimes though you might want to test how the fix works in you host Eclipse. There are two main ways to perform this testing:

  1. You can build Eclipse from scratch yourself, using the steps from the platform build wiki. This is by far the most difficult way to get a host Eclipse with your change in it.
  1. You can use the export feature from PDE to install your change as a feature patch in your host. There is a wizard to help you with the export, but you can read more about it in the Eclipse help doc and in a good blog post from EclipseScource.

Smoke Tests

Smoke testing can be done following the manual test script. Find the section that best covers your fix and run through the steps, this will give you an extra level of confidence that the changes you are proposing are of high quality.

This kind of testing is good to do regardless of how you test your fix, whether you do target testing or host testing.

Commit Messages

When working on a Gerrit-contributed fix it is mandatory to provide a commit message.

In Debug there is a specific form we allow for that message:

  1. Copy the bug title from the bugzilla and paste it in as the first line of the commit message
  2. Add "Change-id: <id>"
  3. Add "Signed-off-by: <your_name> <your_email_adress>" (see "Legal Paperwork" below).

For a bit more information committing from within Eclipse give the EGit section on committing from the staging view a read.