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 "Ant/Developers"

< Ant
(Connect to the Eclipse Repository)
m (Using Gerrit: Fixing broken link)
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
{{Ant}}
 +
 
== Overview ==
 
== Overview ==
 
There are many ways that you as a member of the community can get involved and contribute to the Platform Ant project.
 
There are many ways that you as a member of the community can get involved and contribute to the Platform Ant project.
Line 12: Line 14:
 
*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 [https://bugs.eclipse.org/bugs/buglist.cgi?cmdtype=runnamed&namedcmd=Inbox Inbox].
 
*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 [https://bugs.eclipse.org/bugs/buglist.cgi?cmdtype=runnamed&namedcmd=Inbox Inbox].
  
== Mailing Lists ==
+
= Contributing to Platform Ant =
platform-ant-dev@eclipse.org
+
Platform Ant is 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 Platform Ant in general, or for questions about its internals, contact [mailto:platform-ant-dev@eclipse.org platform-ant-dev@eclipse.org].
  
== Writing Code for Ant ==
+
= Creating Bug Reports =
All development on platform Ant 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 Eclipse [[Development_Conventions_and_Guidelines | coding guidelines]]. When working on Ant code, you should set your compiler compliance and source level to 1.4 (Java > Compiler Preference Page).
+
When filing bugs against the Platform Ant project, we ask that you use your better judgment, and most importantly common sense before filing a bug.  
  
Your first step is to download an Eclipse build. You can download a the Eclipse platform [http://download.eclipse.org 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.
+
Specifically:
  
== Connect to the Eclipse Repository ==
+
*Search bugzilla for existing bugs like yours BEFORE you file it. Resolving duplicates is time consuming.
The easiest way to download the correct projects from CVS is to use our [[Media:Ant.psf|Ant project set file]]. Download the psf file 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 Ant projects from CVS. More information about project set files can be found on the PSF Wiki Page.
+
*Be sure that what happened is really a bug. For example if all you see is an entry in the log files that mentions Ant 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 buildfile?". This is not a bug.
 +
*Bugs should be filed against the PLATFORM-ANT 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.
  
Create a CVS Repository Location with the following information:
+
By default, bugs filed against a Ant component will be assigned to an inbox account. Interested parties watch this inbox user to see incoming bugs. Committers or the Ant team lead will move bugs from the inbox account when someone is actively working on a bug.
  
{| class="wikitable" border="1" width="25%"
+
= Make a Contribution =
|-
+
! 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 Ant projects:
+
Before starting to develop an enhancement or fix for Platform Ant, it is important that you get in touch with the project. We track ideas for enhancements and bug reports in the Eclipse bugzilla ([https://bugs.eclipse.org/bugs/buglist.cgi?classification=Eclipse&component=Ant&list_id=8732437&product=Platform Platform Ant]), 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 [mailto:platform-ant-dev@eclipse.org platform-ant-dev@eclipse.org].
 +
 
 +
== Get the Source ==
 +
Platform Ant is hosted in Git and can be viewed online: [http://git.eclipse.org/c/platform/eclipse.platform.git/ Platform Ant].
 +
 
 +
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 set up in Eclipse the [https://wiki.eclipse.org/EGit/User_Guide#Importing_projects projects you want to import] are:
 
<pre>
 
<pre>
 
org.eclipse.ant.core
 
org.eclipse.ant.core
Line 59: Line 50:
 
org.eclipse.ant.tests.core
 
org.eclipse.ant.tests.core
 
org.eclipse.ant.tests.ui
 
org.eclipse.ant.tests.ui
org.eclipse.core.externaltools
 
org.eclipse.ui.externaltools
 
 
</pre>
 
</pre>
Your workspace setup is now complete. The Platform Ant 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 Platform Ant projects have the "Plug-in Dependencies" library on their Java build path.
 
  
When you upgrade your Eclipse install, the Platform Ant 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.
+
Your workspace setup is now complete. You do not have to import all of the dependencies for the Ant 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 Ant projects will automatically compile against the new plugins.
  
== Launching the Run-time Workbench ==
+
It is good practice to develop the latest versions of the Ant plug-ins using the latest version of Eclipse. For example, as of this writing, Eclipse 4.4 would be used to develop Ant 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.
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.
+
== 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:
 +
{{codeblock|/*******************************************************************************
 +
* Copyright (c) 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
 +
*******************************************************************************/}}
 +
* Platform Ant 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 ==
 
== 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.
+
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. Platform Ant accepts contributions using patches attached to the corresponding bugzilla or [[#Using_gerrit|Gerrit review requests]] (as we will discuss in the next section).
  
== Creating Bug Reports ==
+
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]'.
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.
+
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.
#Be sure that what happened is really a bug. For example if all you see is an entry in the log files that mentions Ant 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 buildfile?". This is not a bug.
+
#Bugs should be filed against the PLATFORM-ANT component. New feature requests should be filed with a severity of "enhancement".
+
  
By default, bugs filed against an Ant component will be assigned to an inbox account. Interested parties watch this inbox user to see incoming bugs. Committers or the Ant team lead move bugs from the inbox account when someone is actively working on a bug.
+
== Using Gerrit ==
  
== Bug Lifecycle ==
+
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 [http://www.vogella.com/articles/Gerrit/article.html#eclipsegerritcontribution Lars Vogel's tutorial] for contributing via Gerrit.
All bugs for the Platform Ant 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.
+
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.
*DUPLICATE/INVALID/WORKSFORME/WONTFIX - If a bug is a duplicate of another bug or if an Ant 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 an Ant 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:
+
The Platform Ant Gerrit respositories are:
 +
*Anonymous git - <code>git://git.eclipse.org/gitroot/platform/eclipse.platform</code>
 +
*Anonymous HTTP - <code>https://git.eclipse.org/r/platform/eclipse.platform</code>
 +
*SSH - <code>ssh://<userid>@git.eclipse.org:29418/platform/eclipse.platform</code>
 +
*HTTP - <code>https://<userid>@git.eclipse.org/r/platform/eclipse.platform</code>
  
#Reassign the bug to the Ant committer who will fix the bug.
+
Once you have Gerrit configured for the Ant 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.
#Create a patch of the proposed fixes for the bug.
+
 
#Commit the code changes to CVS.
+
== Testing the Fix ==
#Using the REVIEW flags add the other committer(s) who are to verify the bug (with the '?' flag).
+
=== Unit Tests ===
#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.
+
Platform Ant has 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 committer will do is run these tests, and if any fail your contribution will be immediately rejected.
#VERIFIED-FIXED - Bugs are marked as VERIFIED-FIXED once someone verifies the fix that was checked into CVS. Bugs are always verified by an Ant 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.
+
 
 +
Luckily though, there are shared test configurations that you can use to run these tests exactly as the committers do. They are found
 +
in:
 +
*<code>org.eclipse.ant.tests.core</code>
 +
*<code>org.eclipse.ant.tests.ui</code>
 +
 
 +
To run these shared configurations simply open the launch configuration dialog, look under the '''JUnit Plug-in Test''' type to find the <code>Ant Core Test Suite</code> and the <code>Ant UI Test Suite</code> configurations.
 +
 
 +
=== Target Testing ===
 +
 
 +
After you've run the [[#Unit_tests|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 [[#Smoke_tests|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 [[#Unit_tests|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:
 +
 
 +
#You can build Eclipse from scratch yourself, using the steps from the [https://wiki.eclipse.org/Platform-releng/Platform_Build platform build] wiki. This is by far the most difficult way to get a host Eclipse with your change in it.
 +
 
 +
#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 [http://help.eclipse.org/kepler/index.jsp?topic=%2Forg.eclipse.pde.doc.user%2Ftasks%2Fui_export_install_into_host.htm Eclipse help doc] and in a good [http://eclipsesource.com/blogs/2009/04/23/export-into-the-host-eclipse/ blog post from EclipseScource].
 +
 
 +
=== Smoke Tests ===
 +
 
 +
Smoke testing can be done following the [[Ant/Test_Script | 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|target testing]] or [[#Host_testing|host testing]].
 +
 
 +
== Commit Messages ==
 +
When working on a Gerrit-contributed fix it is mandatory to provide a commit message.
 +
 
 +
In Ant there is a specific form we allow for that message:
 +
#Copy the bug title from the bugzilla and paste it in as the first line of the commit message
 +
#Add "Change-id: <id>"
 +
#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 [https://wiki.eclipse.org/EGit/User_Guide#Committing_with_the_Staging_View committing from the staging view] a read.
  
 
== Test Passes ==
 
== Test Passes ==
Line 110: Line 148:
  
 
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.
 
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.
 +
 +
== Apache Ant ==
 +
The Platform Ant support relies on Apache Ant. Unfortunately, platform Ant does not directly consume Apache Ant, but instead uses a version from [[Orbit|Orbit]]. The version in Orbit needs to be updated as each new version of Apache Ant is released.
 +
 +
Instructions for updating Apache Ant in Orbit can be found on the [[Ant/How_to_add_new_Ant_versions | how-to page]].
 +
 +
=== Apache Ant Source ===
 +
You can bring the Orbit version of Apache Ant into your workspace if you need for debugging (but it should be fine to debug through the version installed in Eclipse). The version that is pre-installed in Eclipse comes from [https://wiki.eclipse.org/Orbit Orbit], so to get the source you have to check out the [https://wiki.eclipse.org/Orbit/FAQ#How_do_I_work_with_a_bundle_in_Orbit.3F corresponding branch] (as of this writing that is v1_9_2).

Latest revision as of 16:11, 29 June 2014

Platform Ant
Website
Download
Community
Mailing ListForumsIRCmattermost
Issues
OpenHelp WantedBug Day
Contribute
Browse Source

Overview

There are many ways that you as a member of the community can get involved and contribute to the Platform Ant project.

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 platform-ant-inbox@eclipse.org to your watch list.

Here are some ways you can contribute:

  • Participate in Bug Day.
  • Write code, developing source artifacts and patches for the Ant projects.
  • File bug reports in Bugzilla for defects you find.
  • Participate in a milestone test pass.
  • 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.

Contributing to Platform Ant

Platform Ant is 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 Platform Ant in general, or for questions about its internals, contact platform-ant-dev@eclipse.org.

Creating Bug Reports

When filing bugs against the Platform Ant 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 Ant 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 buildfile?". This is not a bug.
  • Bugs should be filed against the PLATFORM-ANT 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 Ant component will be assigned to an inbox account. Interested parties watch this inbox user to see incoming bugs. Committers or the Ant team lead will move bugs from the inbox account when someone is actively working on a bug.

Make a Contribution

Before starting to develop an enhancement or fix for Platform Ant, it is important that you get in touch with the project. We track ideas for enhancements and bug reports in the Eclipse bugzilla (Platform Ant), 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 platform-ant-dev@eclipse.org.

Get the Source

Platform Ant is hosted in Git and can be viewed online: Platform Ant.

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.ant.core
org.eclipse.ant.launching
org.eclipse.ant.ui
org.eclipse.ant.tests.core
org.eclipse.ant.tests.ui

Your workspace setup is now complete. You do not have to import all of the dependencies for the Ant 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 Ant projects will automatically compile against the new plugins.

It is good practice to develop the latest versions of the Ant plug-ins using the latest version of Eclipse. For example, as of this writing, Eclipse 4.4 would be used to develop Ant 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) 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
*******************************************************************************/
  • Platform Ant 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. Platform Ant accepts 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 Platform Ant Gerrit respositories are:

Once you have Gerrit configured for the Ant 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

Platform Ant has 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 committer 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.ant.tests.core
  • org.eclipse.ant.tests.ui

To run these shared configurations simply open the launch configuration dialog, look under the JUnit Plug-in Test type to find the Ant Core Test Suite and the Ant UI 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 Ant 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 Ant team does an intense one-day test pass where we test all of the functionality of the Ant 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.

Apache Ant

The Platform Ant support relies on Apache Ant. Unfortunately, platform Ant does not directly consume Apache Ant, but instead uses a version from Orbit. The version in Orbit needs to be updated as each new version of Apache Ant is released.

Instructions for updating Apache Ant in Orbit can be found on the how-to page.

Apache Ant Source

You can bring the Orbit version of Apache Ant into your workspace if you need for debugging (but it should be fine to debug through the version installed in Eclipse). The version that is pre-installed in Eclipse comes from Orbit, so to get the source you have to check out the corresponding branch (as of this writing that is v1_9_2).

Back to the top