Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Debug/Developers"

Line 1: Line 1:
 
{{Debug}}
 
{{Debug}}
= Contributing to JDT or Platform Debug =
+
== 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 [https://wiki.eclipse.org/Development_Resources/HOWTO/Nominating_and_Electing_a_New_Committer New Committer Election]). For more information about contributing to JDT or Platform Debug in general, or for questions about its internals, contact [mailto:jdt-debug-dev@eclipse.org jdt-debug-dev@eclipse.org] or [mailto:platform-debug-dev@eclipse.org platform-debug-dev@eclipse.org] respectively.
 
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 [https://wiki.eclipse.org/Development_Resources/HOWTO/Nominating_and_Electing_a_New_Committer New Committer Election]). For more information about contributing to JDT or Platform Debug in general, or for questions about its internals, contact [mailto:jdt-debug-dev@eclipse.org jdt-debug-dev@eclipse.org] or [mailto:platform-debug-dev@eclipse.org 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 [https://wiki.eclipse.org/Eclipse/Bug_Tracking#Severity 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. 
 +
 +
The tags currently being used are:
 +
* '''[breakpoints]''' breakpoint support
 +
* '''[breadcrumb]''' compact mode in debug view
 +
* '''[console]''' console view support
 +
* '''[debug context]''' active debug context in windows and views management
 +
* '''[debug view]''' debug view (aka launch view) support
 +
* '''[display]''' display view
 +
* '''[doc]''' Documentation
 +
* '''[evaluations]''' JDT evaluations
 +
* '''[examples]''' DSF Examples
 +
* '''[expr]/[expressions]''' expressions view support
 +
* '''[external tools]''' external tools support
 +
* '''[flex]/[Flexible Hierarchy]''' Flexible Hierarchy viewer used by debugger views
 +
* '''[help]''' context sensitive documentation
 +
* '''[hover]''' editor hover popup
 +
* '''[i18n]''' internationalization
 +
* '''[launch]/[launching]''' launch configurations, delegates, UI, etc.
 +
* '''[logical struct]''' logical structures support in variables/expressions view
 +
* '''[memory]/[Memory View]''' memory view support
 +
* '''[menu]''' main menu, context menus, and toolbars
 +
* '''[modules]''' modules view support
 +
* '''[patch]''' the bugzilla has a patch attached
 +
* '''[perspectives]''' perspective activation upon start of debugging
 +
* '''[reg]/[registers]''' register view support
 +
* '''[run control]''' support for run control commands
 +
* '''[source lookup]''' mapping debugger sources to the host file system, opening the editor
 +
* '''[standard model]''' related to standard debug model api
 +
* '''[test]''' automated testing
 +
* '''[var]/[variables]''' variables view support
 +
* '''[resolver]''' workspace variables resolver
 +
* '''[viewmgmt]/[View Management]''' Auto-opening of views in perspective upon stat of debugging.
  
 
== Starting a Contribution ==
 
== Starting a Contribution ==
Line 9: Line 59:
 
If you want to do an enhancement but don't know where to start, you can also just ask on either [mailto:jdt-debug-dev@eclipse.org jdt-debug-dev@eclipse.org] or [mailto:platform-debug-dev@eclipse.org platform-debug-dev@eclipse.org].
 
If you want to do an enhancement but don't know where to start, you can also just ask on either [mailto:jdt-debug-dev@eclipse.org jdt-debug-dev@eclipse.org] or [mailto:platform-debug-dev@eclipse.org platform-debug-dev@eclipse.org].
  
== Get the Source ==
+
=== Get the Source ===
 
JDT and Platform Debug are hosted in Git and can be viewed online: [http://git.eclipse.org/c/jdt/eclipse.jdt.debug.git/ JDT Debug], [http://git.eclipse.org/c/platform/eclipse.platform.debug.git/ Platform Debug].
 
JDT and Platform Debug are hosted in Git and can be viewed online: [http://git.eclipse.org/c/jdt/eclipse.jdt.debug.git/ JDT Debug], [http://git.eclipse.org/c/platform/eclipse.platform.debug.git/ 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 [https://wiki.eclipse.org/EGit/User_Guide#Starting_from_existing_Git_Repositories EGit howto page].
 
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 [https://wiki.eclipse.org/EGit/User_Guide#Starting_from_existing_Git_Repositories EGit howto page].
  
Once your repository is imported in Eclipse the projects you want to import are:
+
Once your repository is set up in Eclipse the [https://wiki.eclipse.org/EGit/User_Guide#Importing_projects projects you want to import] are:
 
<pre>
 
<pre>
 
org.eclipse.core.externaltools
 
org.eclipse.core.externaltools
Line 32: Line 82:
 
org.eclipse.ui.externaltools
 
org.eclipse.ui.externaltools
 
</pre>
 
</pre>
 
  
 
Your workspace setup is now complete. The Debug 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 projects have the "Plug-in Dependencies" library on their Java build path.
 
Your workspace setup is now complete. The Debug 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 projects have the "Plug-in Dependencies" library on their Java build path.
Line 38: Line 87:
 
When you upgrade your Eclipse install, the Debug 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.
 
When you upgrade your Eclipse install, the Debug 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.
  
== Creating Patches ==
+
=== 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.
+
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 [[#Using_gerrit|Gerrit review requests]] (as we will discuss in the next section).
  
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.
+
To create a patch, follow the simple steps on the [https://wiki.eclipse.org/EGit/User_Guide#Patches 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]'.
  
== Using Gerrit ==
+
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.
  
== Creating Bug Reports ==
+
=== Using Gerrit ===
  
When filing bugs against the Debug Project, we ask that you use your better judgment, and most importantly common sense before filing a bug.  
+
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.
  
Specifically:
+
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 [https://wiki.eclipse.org/EGit/User_Guide#Gerrit_Configuration EGit Gerrit set up] wiki.
  
#Search bugzilla for existing bugs like yours BEFORE you file it. Resolving duplicates is time consuming.
+
While configuring Gerrit the debug Gerrit repos are:
#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".
+
  
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.
+
# JDT Debug  
 +
Anonymous git - <code>git://git.eclipse.org/gitroot/jdt/eclipse.jdt.debug</code>
 +
Anonymous HTTP - <code>https://git.eclipse.org/r/jdt/eclipse.jdt.debug</code>
 +
SSH - <code>ssh://<userid>@git.eclipse.org:29418/jdt/eclipse.jdt.debug</code>
 +
HTTP - <code>https://<userid>@git.eclipse.org/r/jdt/eclipse.jdt.debug</code>
  
== Bug Lifecycle ==
+
# Platform Debug
 +
Anonymous git - <code>git://git.eclipse.org/gitroot/platform/eclipse.platform.debug</code>
 +
Anonymous HTTP - <code>https://git.eclipse.org/r/platform/eclipse.platform.debug</code>
 +
SSH - <code>ssh://<userid>@git.eclipse.org:29418/platform/eclipse.platform.debug</code>
 +
HTTP - <code>https://<userid>@git.eclipse.org/r/platform/eclipse.platform.debug</code>
  
All bugs for the Debug components follow the same lifecycle. All committers and contributors must adhere to this lifecycle to ensure all defects are tracked and handled accordingly.
+
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|Commit Messages]] section ''before'' you commit / push your change.
  
*NEW - All newly filed bugs start out in the NEW state.
+
=== Unit Tests ===
*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 a patch for the bug has been added to the bug report and committed to CVS. When requesting that someone verify a bug, we set the review flag for the person we want to verify it and add them to the CC list, if not already present. If for some reason the person you want to verify the bug does not have privileges to set the review flag, mention them in a comment asking to verify the bug and ensure they are on the CC list.
+
  
Bugzilla is picky about the state changes it allows, so we follow these steps to maximize efficiency:
+
=== Commit Messages ===
 +
When working on a Gerrit-contributed fix it is mandatory to provide a commit message.
  
#Reassign the bug to the Debug committer who will fix the bug.
+
In Debug there is a specific form we allow for that message:
#Create a patch of the proposed fixes for the bug and attach it to the bug report.
+
#Copy the bug title from the bugzilla and paste it in as the first line of the commit message
#Commit the code changes to CVS.
+
#Add "Change-id: <id>"
#Using the REVIEW flags add the other committer(s) who are to verify the bug (with the '?' flag).
+
#Add "Signed-off-by: <your_name> <your_email_adress>" (see "Legal Paperwork" below).
#Add the committer(s) involved in the review to the CC list - to ensure they are notified of a review request.
+
#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.
+
 
+
=== Maintenance Release Fixes ===
+
When committing a fix into a maintenance branch of a released version, a duplicate bug record should be created.  The bug may start with a comment "This is a duplicate of bug xxx for x.y.x release.
+
 
+
=== Bug Summary Tags ===
+
When bugs are triaged, a committer may add tags in square brackets to identify which feature the bug is related to.  The tags currently being used are:
+
  
* '''Debugger'''
+
For a bit more information committing from within Eclipse give the EGit section on [https://wiki.eclipse.org/EGit/User_Guide#Committing_with_the_Staging_View committing from the staging view] a read.
** '''[breakpoints]''' breakpoint support
+
** '''[breadcrumb]''' compact mode in debug view
+
** '''[console]''' console view support
+
** '''[debug context]''' active debug context in windows and views management
+
** '''[debug view]''' debug view (aka launch view) support
+
** '''[display]''' display view
+
** '''[doc]''' Documentation
+
** '''[evaluations]''' JDT evaluations
+
** '''[examples]''' DSF Examples
+
** '''[expr]/[expressions]''' expressions view support
+
** '''[external tools]''' external tools support
+
** '''[flex]/[Flexible Hierarchy]''' Flexible Hierarchy viewer used by debugger views
+
** '''[help]''' context sensitive documentation
+
** '''[hover]''' editor hover popup
+
** '''[i18n]''' internationalization
+
** '''[launch]/[launching]''' launch configurations, delegates, UI, etc.
+
** '''[logical struct]''' logical structures support in variables/expressions view
+
** '''[memory]/[Memory View]''' memory view support
+
** '''[menu]''' main menu, context menus, and toolbars.
+
** '''[modules]''' modules view support
+
** '''[perspectives]''' perspective activation upon start of debugging
+
** '''[reg]/[registers]''' register view support
+
** '''[run control]''' support for run control commands
+
** '''[source lookup]''' mapping debugger sources to the host file system, opening the editor
+
** '''[standard model]''' related to standard debug model api
+
** '''[test]''' automated testing
+
** '''[var]/[variables]''' variables view support
+
** '''[resolver]''' workspace variables resolver
+
** '''[viewmgmt]/[View Management]''' Auto-opening of views in perspective upon stat of debugging.
+
  
 
== Test Passes ==
 
== Test Passes ==

Revision as of 13:57, 31 March 2014

Platform Debug
Website
Download
Community
Mailing ListForumsIRCmattermost
Issues
OpenHelp WantedBug Day
Contribute
Browse Source
JDT Debug
Website
Download
Community
Mailing ListForumsIRCmattermost
Issues
OpenHelp WantedBug 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:

  1. Search bugzilla for existing bugs like yours BEFORE you file it. Resolving duplicates is time consuming.
  2. 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.
  3. Bugzilla is not a forum. Do not ask questions on bugzilla like "how do I create a HelloWorld class?". This is not a bug.
  4. Bugs should be filed against the PLATFORM-DEBUG or the JDT-DEBUG component. New feature requests should be filed with a severity of "enhancement".
  5. 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).
  6. 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.

The tags currently being used are:

  • [breakpoints] breakpoint support
  • [breadcrumb] compact mode in debug view
  • [console] console view support
  • [debug context] active debug context in windows and views management
  • [debug view] debug view (aka launch view) support
  • [display] display view
  • [doc] Documentation
  • [evaluations] JDT evaluations
  • [examples] DSF Examples
  • [expr]/[expressions] expressions view support
  • [external tools] external tools support
  • [flex]/[Flexible Hierarchy] Flexible Hierarchy viewer used by debugger views
  • [help] context sensitive documentation
  • [hover] editor hover popup
  • [i18n] internationalization
  • [launch]/[launching] launch configurations, delegates, UI, etc.
  • [logical struct] logical structures support in variables/expressions view
  • [memory]/[Memory View] memory view support
  • [menu] main menu, context menus, and toolbars
  • [modules] modules view support
  • [patch] the bugzilla has a patch attached
  • [perspectives] perspective activation upon start of debugging
  • [reg]/[registers] register view support
  • [run control] support for run control commands
  • [source lookup] mapping debugger sources to the host file system, opening the editor
  • [standard model] related to standard debug model api
  • [test] automated testing
  • [var]/[variables] variables view support
  • [resolver] workspace variables resolver
  • [viewmgmt]/[View Management] Auto-opening of views in perspective upon stat of debugging.

Starting 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. The Debug 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 projects have the "Plug-in Dependencies" library on their Java build path.

When you upgrade your Eclipse install, the Debug 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.

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.

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.

While configuring Gerrit the debug Gerrit repos are:

  1. JDT Debug

Anonymous git - git://git.eclipse.org/gitroot/jdt/eclipse.jdt.debug Anonymous HTTP - https://git.eclipse.org/r/jdt/eclipse.jdt.debug SSH - ssh://<userid>@git.eclipse.org:29418/jdt/eclipse.jdt.debug HTTP - https://<userid>@git.eclipse.org/r/jdt/eclipse.jdt.debug

  1. Platform Debug

Anonymous git - git://git.eclipse.org/gitroot/platform/eclipse.platform.debug Anonymous HTTP - https://git.eclipse.org/r/platform/eclipse.platform.debug SSH - ssh://<userid>@git.eclipse.org:29418/platform/eclipse.platform.debug HTTP - https://<userid>@git.eclipse.org/r/platform/eclipse.platform.debug

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.

Unit Tests

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.

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 script. The script defines a basic overview of what must be tested in each section.

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.

Back to the top