Difference between revisions of "Ant/Developers"

Revision as of 14:19, 2 January 2014

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.

Mailing Lists

platform-ant-dev@eclipse.org

Writing Code for Ant

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 coding guidelines. When working on Ant code, you should set your compiler compliance and source level to 1.4 (Java > Compiler Preference Page).

Your first step is to download an Eclipse build. You can download a the Eclipse platform 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

Before you can grab the source for Ant you will have to install the Git tools in Eclipse, as they do not come pre-installed.

Once you have the Git team provider support installed, head over to the Git repository page and clone the repo. If you are not familiar with cloning repositories / using the tooling, give the Git wiki a read.

Once you have the repository cloned, you can import all of the Ant projects into your workspace.

The Ant projects to import:

org.eclipse.ant.core
org.eclipse.ant.launching
org.eclipse.ant.ui
org.eclipse.ant.tests.core
org.eclipse.ant.tests.ui
org.eclipse.core.externaltools
org.eclipse.ui.externaltools

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.

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.

Pushing to Gerrit

Platform Ant uses Gerrit as its main resource to accept contributions. Patches are still welcome, but Gerrit is the preferred method.

To use Gerrit for Platform Ant, you must clone the repository as mentioned in the connect to the repository section above, and then enable Gerrit support. To set up Gerrit on a repository, read the configuration wiki page.

Once Gerrit is configured and working, you can push your proposed changes to Gerrit for review by one of the committers.

Creating Bug Reports

When filing bugs against the Ant 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 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.
3. Bugzilla is not a forum. Do not ask questions on bugzilla like "how do I create a buildfile?". This is not a bug.
4. 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.

Bug Lifecycle

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.
• 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:

1. Reassign the bug to the Ant committer who will fix the bug.
2. Create a patch of the proposed fixes for the bug.
3. Commit the code changes to CVS.
4. Using the REVIEW flags add the other committer(s) who are to verify the bug (with the '?' flag).
5. Add the committer(s) involved in the review to the CC list - to ensure they are notified of a review request.
6. Mark the bug RESOLVED-FIXED with a request to verify.
7. 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.

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.