Mylar Contributor Reference

Contributing

• Introduction
• Workspace setup
• Contributing patches
• Building a distribution
• Additional References

Extending Mylar

• Extensibility Overview
• Task repository requirements

Introduction

Those interested in contributing should start out by emailing mylar-dev@eclipse.org in order to get an idea of the current priorities.  Also refer to the list of reports marked help wanted. 

Workspace setup

• Building Mylar feature from HEAD requires the latest Eclipse milestone release and JDK 1.5.  Associate the J2SE-1.5 with your installed JRE on the Execution Environments preference page.
• In the CVS Repositories view, add the following CVS location: HOST = dev.eclipse.org  Repository Path: /cvsroot/technology.
  If you do not have an account you may enter anonymous for the user name and leave the password blank.
• Check out all of the projects under org.eclipse.mylar (except mylar.jira, mylar.sandbox, mylar.viz, and mylar.zest.* which have additional dependencies).  There should be no errors or warnings.
• Run org.eclipse.mylar.tests.AllTests as a JUnit Plug-in Test, with assertions enabled.  All tests should pass and there should be no console output.  The tests workbench window can be in the foreground or background, but should not be interacted with during the test execution.
  • Add the following to the test configuration under Arguments -> VM Arguments: -enableassertions -Xmx384M

Working in bootstrap mode

• To work from the latest copy of Mylar in HEAD as some committers do, set up a fresh workspace launched from an Eclipse that does not have Mylar installed (recommended, not required), and check out Mylar into it.
• Then create a new Launch Configuration, point it at your workspace, and work in that.  The launching workspace will typically use very little memory, but if you have a memory constrained machine you can kill its java process.

Working with JIRA Integration

• Get the latest Subclipse plug-in, e.g. from the following update site: subclipse.tigris.org/update_1.0.x
• Set up a Subversion repository for JIRA Dashboard (see the JIRA Dahsboard doc for troubleshooting):
  • username: guest
  • password: <blank>
  • repository: http://jira-dashboard.tigris.org/svn/jira-dashboard/trunk
• Check out the JIRA Dashboard Core featureres:
  • org.tigris.jira.core
  • org.tigris.jira.core.soap
  • org.tigris.jira.core-feature
  • org.apache.axis
  • org.apache.commons

Contributing patches

All contributions to Mylar including patches should be made by using Mylar in order to ensure that we eat our our own dog food.  A task context should be attached to each patch to make applying and evolving it easier.

• Each patch should correspond to a single bug report, and a single patch should be made for each set of changes to be reviewed.
• With few exceptions patches should be accompanied by a JUnit test, and in general unit tests are one of the most valuable and long-lived contributions.  If you are having trouble writing a test (e.g. trickiness verifying what happens in the UI) comment on the corresponding bug report so that we can point you at similar test cases or consider extending the test harness if needed.
• Minimize the amount of changes to existing code to make review easier. 
• Synchronize often to ensure you have the latest code.  Once you start modifying resources, put the Synchronize view in Outgoing mode and press the Change Set button so that Mylar tracks the context for the patch.
• Before creating a new JUnit test class class check the components test suite for similar test cases (e.g. AllTasklistTests).
• Set the formatter by importing org.eclipse.mylar/developer/javaFormatterSettings.xml into Window -> Preferences -> Java -> Code Style -> Formatter.  Format code using Eclipse's formatter (Ctrl+Shift+F) and ensure that no  have been added.
• Ensure that there is no console output.  For logging errors use MylarStatusHandler.

To submit:

• Ensure there are no build errors, warnings, and that org.eclipse.mylar.tests.AllTests passes.
• Synchronize using Incoming mode and ensure that there are no conflicts, and merge them locally if there are.
• Right click the task context change set (or the project containing the patch--patches should be made for a project, not a file), press Team -> Create Patch, and make the file suffix ".txt".
• Attach the patch to the bug report, and indicate in the comment what testing was done to validate it (e.g. unit test coverage, manual tests performed).
• Attach the task context to the bug report.

Building a distribution

• Using PDE Build support to create a Mylar distribution from HEAD, using a plain Eclipse 3.2
  • org.eclipse.mylar-feature/feature.xml -> Overview -> change version number to current date (e.g. 0.4.7.v20060125-0800)
    • On Plug-ins tab -> Versions... -> Force feature version into plug-in and fragment manifests
    • Repeat above for org.eclipse.mylar-bugzilla-feature.xml
  • org.eclipse.mylar-site/e3.2/site.xml
    • Delete old features (grayed out)
    • Add new mylar-bugzilla and mylar features
    • Hit Build All (if this fails restart Eclipse and try again)
• To install, add the path of org.eclipse.mylar-site/e3.2/site.xml as a local update site
• Bugzilla support can be built independently of the Mylar UI by checking out the following projects mylar.bugzilla.core, mylar.bugzilla.ui, mylar.tasklist, mylar.core

Merging and building the 3.1 branch

• Right-click the org.eclipse.mylar.java, mylar.ide, and mylar.xml project, Team -> Switch to Another Branch..., then Refresh the Branches and select e_3_1
• The list of files that should not be overwritten is in: org.eclipse.mylar-site/merge.text

Deploying

• Instructions are in org.eclipse.mylar-site/deploy.txt

Additional references

The following books and links refer to the principles behind Mylar's development process, Java, and Eclipse coding conventions.

Eclipse Programming	Java Programming	Planning

Extensibility overview

Following the Eclipse conventions, Mylar will not make any API guarantees until the 1.0 release.  However, a driving goal of the Mylar project is to provide a task management and focused UI framework that can be easily extended by any Eclipse SDK and RCP based applications.  The Mylar components are loosely coupled by preliminary extension points and APIs, and these will be stabilizing between the 0.5 and 1.0 releases.  We strongly recommend that anyone interest in extending Mylar email mylar-dev@eclipse.org regarding the status of Mylar extensibility.

Task repository requirements

Mylar can be extended to any task/bug/issue/story repository or tracker by creating a Repository Connector that links Mylar's task management facilities with the repository.  Connection to the task repository is handled by the connector (e.g. via HTTP for the Bugzilla Connector, via SOAP for the JIRA Connector).  The following are required to support task list integration:

• Tasks must be uniquely identifiable by a per-repository integer or string handle (e.g.  repository: https://bugs.eclipse.org/bugs, id 138144)
• Mechanism for executing a string-based query and returning task IDs (e.g. submit query via SOAP, retrieve matching task IDs)
• Mechanism for accessing all of the task attributes (e.g. description, priority, comment thread)

The following are optional:

• Notification of changes (e.g. RSS-based notification of an update made via that web UI)
• Retrieving a user's saved queries (e.g. searches or filters saved via the web UI)

The following additional mechanisms enable task authoring:

• Retrieving all of the operations possible on a task given login credentials (e.g. ability to reassign, change priority)
• Accessing all of the repository attributes (e.g. lists of products, components, versions)
• Setting any of the task's attributes (e.g. changing components, reassigning)
• Adding and retrieving attachments (e.g. adding screenshots)