The Mylyn project is structured into the following update sites and distributions. Mylyn extensions are split into two different categories. ''Connectors'' extend Mylyn to different task management systems. ''Bridges'' focus the artifacts that you work with when you activate a task.

+

The Mylyn project is structured into sub-projects that address different areas of Application Life-cycle Management. Please see [[Mylyn/Charter]] for the top-level project charter.

−

Please see [[Mylyn/Charter]] for the top-level project charter.

+

Artifacts are published in a number of [[Mylyn/Repositories]]. The [http://eclipse.org/mylyn/downloads/ main repository] aggregates sub-projects that participate in Mylyn releases. The participating projects are listed in the [http://www.eclipse.org/projects/project-plan.php?projectid=mylyn project plan]. The main Mylyn update site features are mature components that are supported by the Mylyn project committers and may be distributed as part of the [http://www.eclipse.org/downloads/ Eclipse Downloads].

−

=== Main ===

+

Sub-projects are encouraged to provide a framework component and reference implementations called ''Connectors'' that extend Mylyn to different task management systems and focus the artifacts that you work with when you activate a task (formerly called ''Bridges'').

−

The main Mylyn update site features are mature components that are supported by the Mylyn project committers and distributed as part of the [http://www.eclipse.org/downloads/ Eclipse Downloads].

+

=== Feature Maturity ===

−

Features:

+

Mylyn features vary in UI maturity and availibility of support. The following is a guideline for what it takes to move from experimentation through to maturity. (Note that this is partially based on the [http://www.eclipse.org/projects/dev_process/development_process.php#6_2_3_Incubation Eclipse project lifecycle] and could converge further with that lifecycle if Mylyn were split into a separate incubation project or subprojects.)

* UI quality: Eclipse SDK features have set a very high quality and UI consistency bar that needs to be met in order to make it possible to improve users' productivity with Eclipse.

+

* UI simplicity: the Mylyn project's goal is to simplify and streamline the user experience. A simple and self-evident UI also helps ensure a manageable support burden on the component.

+

* Availability of support: the feature must have an owner or organization with a long-term commitment to the quality of the feature and the ability to provide responsive support for feedback on that feature.

+

* Responsiveness to feedback: the feature owner and other contributors must process and prioritize user feedback and respond to the highest priority needs in a timely manner (e.g. blockers and critical bugs need to be fixed within one release of being submitted, key enhancements help the feature evolve to meet users' needs).

−

Incubator components vary in maturity level and are supported by the component leads.

+

'''Incubation''': available via the nightly update site

−

Features:

+

High quality components that meet most but not all of the above criteria. To graduate, sufficient community feedback must be available on the quality and usability of the component (e.g. 100+ resolved bugs) and committers must vote to determine whether component meets the UI quality and simplicity guidelines.

* Unsupported components used for experimentation and not intended for daily use.

+

* Community interest and contributions determine which experimental features move from the Sandbox into Extras.

+

+

=== Creating New Components ===

+

+

Most sub-projects host a framework component and one or more reference implementations. When new code is brought into Mylyn it may be added as a sub-project, sub-sub-project or as a component of an existing project. The right organisational structure depends on the needs of the development community and the scope and process of the existing projects. Criteria that could qualify a component to be split out as a separate project:

* The committer set of the component is not a subset of the committer set of the framework project.

+

* A component wants to release more frequently than its framework project, i.e. it follows it's own project plan.

+

* A component publishes its own APIs and its scope and community are significant that it requires its separate management structure such as a Bugzilla product, news group etc.

== Getting Started ==

== Getting Started ==

Line 50:

Line 51:

* '''Casual contribution''': we have a large number of very valuable casual contributors who provide patches for their pet bugs, or enhancements that either they would find valuable or that they want to share with others. If you are interested but don't know where to start look first through the short list of bugday bugs, and then through the longer helpwanted list.

* '''Casual contribution''': we have a large number of very valuable casual contributors who provide patches for their pet bugs, or enhancements that either they would find valuable or that they want to share with others. If you are interested but don't know where to start look first through the short list of bugday bugs, and then through the longer helpwanted list.

−

** '''[https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=Mylyn&long_desc_type=allwordssubstr&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=bugday&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailtype1=substring&email1=&emailtype2=notregexp&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0= bugday bugs]''': a short list of highly relevant bugs for getting started

+

** '''[https://bugs.eclipse.org/bugs/buglist.cgi?keywords=bugday;query_format=advanced;keywords_type=allwords;bug_status=UNCONFIRMED;bug_status=NEW;bug_status=ASSIGNED;bug_status=REOPENED;classification=Mylyn bugday bugs]''': a short list of highly relevant bugs for getting started

−

** '''[https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=Mylyn&long_desc_type=allwordssubstr&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=helpwanted&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailtype1=substring&email1=&emailtype2=notregexp&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0= helpwanted bugs]''': a longer list of all bugs targeted at community contributions

+

** '''[https://bugs.eclipse.org/bugs/buglist.cgi?keywords=helpwanted;query_format=advanced;keywords_type=allwords;bug_status=UNCONFIRMED;bug_status=NEW;bug_status=ASSIGNED;bug_status=REOPENED;classification=Mylyn helpwanted bugs]''': a longer list of all bugs targeted at community contributions

* '''Working towards commit rights''': The Eclipse and Mylyn development processes make it easy to make regular contributions without requiring commit rights, but frequent contributors may be interested in earning commit rights. Commit rights come with a significant overhead of user support as well as the need to follow the project's priorities for contributions. They require you to participate in the planning and of the project, and allow you influence the direction of the tool and framework. If you are interested in becoming a committer we recommend letting one of the existing committers know so that they can mentor you and help build a trust relationship. It can also help to identify a separable component of the project that you are interested in taking responsibility for, since Mylyn commit rights are assigned per-component.

* '''Working towards commit rights''': The Eclipse and Mylyn development processes make it easy to make regular contributions without requiring commit rights, but frequent contributors may be interested in earning commit rights. Commit rights come with a significant overhead of user support as well as the need to follow the project's priorities for contributions. They require you to participate in the planning and of the project, and allow you influence the direction of the tool and framework. If you are interested in becoming a committer we recommend letting one of the existing committers know so that they can mentor you and help build a trust relationship. It can also help to identify a separable component of the project that you are interested in taking responsibility for, since Mylyn commit rights are assigned per-component.

Line 62:

Line 63:

Those building both closed and open source tools on top of Mylyn may be interested in evolving the Mylyn APIs to ensure that that the framework meets their needs. We welcome such contributions just as we welcome individuals making improvements to the tool, since they help make Mylyn a better framework for all. The Individual Contributor points above apply to integrators and vendors interested in contributing or earning commit rights. In addition, the following tips may be of interest:

Those building both closed and open source tools on top of Mylyn may be interested in evolving the Mylyn APIs to ensure that that the framework meets their needs. We welcome such contributions just as we welcome individuals making improvements to the tool, since they help make Mylyn a better framework for all. The Individual Contributor points above apply to integrators and vendors interested in contributing or earning commit rights. In addition, the following tips may be of interest:

−

* List your extension on the [[Mylyn Extensions]] page. This will help the Mylyn community become aware of the extension.

+

* List your extension on the [[Mylyn Extensions]] page and in the [http://marketplace.eclipse.org/ Eclipse marketplace]. This will help the Mylyn community become aware of the extension.

* If interested in exploring Mylyn integration, consider dialing into the our weekly call and adding an agenda item on the [[Mylyn Meetings]] page.

* If interested in exploring Mylyn integration, consider dialing into the our weekly call and adding an agenda item on the [[Mylyn Meetings]] page.

* To install additional JRE profiles or if you are unable to obtain a J2SE 1.5 installation install ''Add PDE/API Tools Environment Descriptions'' from the Eclipse project repository that corresponds to your Eclipse environment, e.g. http://download.eclipse.org/eclipse/updates/3.7

−

If you get an error similar to ''Access restriction: The type MimeHeader is not accessible due to restriction on required library /usr/lib/jvm/java-6-sun-1.6.0.07/jre/lib/rt.jar'' either upgrade to Eclipse 3.5M4 or later. Alternatively associate J2SE-1.5 with a version of Java 1.5 (do not use a later version) as described above.

+

=== Checkout ===

=== Checkout ===

−

The source code is hosted in Git. Each sub-project has a separate repository that is accessible through the git, ssh and https protocol. For anonymous access use git or https. Committers need to use ssh or https.

+

The source code is hosted in Gerrit which is a code review system for Git. Each sub-project has a separate repository that is accessible through the git, ssh and https protocol. For anonymous access use git or https. Committers need to use ssh or https.

[http://git.eclipse.org/c/mylyn/ Web access to the Git repositories]

[http://git.eclipse.org/c/mylyn/ Web access to the Git repositories]

Line 96:

Line 97:

'''Release Tags:''' Each release is tagged with <code>R_</code>. For example, Mylyn 2.2.0 for Eclipse 3.4 is tagged as <code>R_2_2_0</code> and the branched Eclipse 3.3 plug-ins are tagged <code>R_2_2_0_e_3_2</code>.

'''Release Tags:''' Each release is tagged with <code>R_</code>. For example, Mylyn 2.2.0 for Eclipse 3.4 is tagged as <code>R_2_2_0</code> and the branched Eclipse 3.3 plug-ins are tagged <code>R_2_2_0_e_3_2</code>.

Mylyn depends on a number of libraries from other Eclipse projects. The <code>org.eclipse.mylyn.releng</code> project provides target environment definitions that specify all required dependencies. After following the steps under [[#Checkout|Checkout]] go to ''Window > Preferences'' and open the ''Target Platform'' page. Select one of the mylyn target definitions depending on the Eclipse platform you are developing against.

+

Mylyn depends on a number of libraries from other Eclipse projects. The <code>org.eclipse.mylyn.releng</code> project provides target environment definitions that specify all required dependencies. After following the steps under [[#Checkout|Checkout]] go to ''Window > Preferences'' and open the ''Target Platform'' page. Select one of the mylyn target definitions. Generally, ''mylyn-dev-base'' is the recommended choice.

+

+

* mylyn-dev-base - Targets the lowest support Eclipse version. Includes sources and additional integration features for development.

+

* mylyn-dev-latest - Targets the highest support Eclipse version. Includes sources and additional integration features for development.

+

* mylyn-e* - Target defintions used by the build. May only contain the minimal requirements excluding sources.

=== API Baseline ===

=== API Baseline ===

Line 176:

Line 189:

Each component has it's own All<Component>Tests suite. If not familiar with running PDE JUnit tests, refer to the [http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.pde.doc.user/guide/tools/launchers/eclipse_main.htm Eclipse Documentation].

Each component has it's own All<Component>Tests suite. If not familiar with running PDE JUnit tests, refer to the [http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.pde.doc.user/guide/tools/launchers/eclipse_main.htm Eclipse Documentation].

−

* Add a ''credentials.properties'' file to org.eclipse.mylyn.context.tests and put the following into it:

+

−

user: <user>

+

Tests that connect to repositories require a ''$HOME/.mylyn/credentials.properties'' file that specifies authentication information. The file needs to have the following content:

−

pass: <pass>

+

user: <user>

−

* For <user> use "tests<at sign>mylyn.eclipse.org". For <pass> use "<project's name lowercase>test". If you have any trouble making this work email mylyn-dev@eclipse.org.

+

pass: <pass>

+

* For <user> use ''tests@mylyn.eclipse.org''. For <pass> use ''mylyntest''. If you have any trouble making this work email mylyn-dev@eclipse.org.

* Add the following to the test configuration under Arguments -> VM Arguments: -enableassertions -Xmx384M

* Add the following to the test configuration under Arguments -> VM Arguments: -enableassertions -Xmx384M

Line 205:

Line 219:

Self-hosting, also known as working bootstrapped (i.e. self-hosted) makes [http://en.wikipedia.org/wiki/Eat_one's_own_dog_food eating your own dog food] easier and avoids having to update to dev builds.

Self-hosting, also known as working bootstrapped (i.e. self-hosted) makes [http://en.wikipedia.org/wiki/Eat_one's_own_dog_food eating your own dog food] easier and avoids having to update to dev builds.

−

The following is an example of how to set up a bootstrap workspace, using Eclipse 3.3 on Windows and a <tt>C:/Dev</tt> workspace directory as an example.

+

The following is an example of how to set up a bootstrap workspace, work and runtime workspace. The result is an folder with the following three workspaces:

* Switch to the Git Repository Exploring Perspective and clone the Git repositories listed under [[Mylyn/Contributor_Reference#Checkout]]

+

* Use Import Projects from the Git Repository Exploring Perspective to add the projects to your workspace

* Create a new Launch Configuration:

* Create a new Launch Configuration:

** Select''Run -> Run...'' -> create a new Eclipse Application.

** Select''Run -> Run...'' -> create a new Eclipse Application.

−

** Call the application ''Mylyn Bootstrap''.

+

** Call the application ''Mylyn Work''.

** On the ''Main'' tab, set the ''Location''

** On the ''Main'' tab, set the ''Location''

−

*** You can use the existing workspace that you used Mylyn with previously

+

*** You can use an existing workspace

−

*** You can create a new workspace (e.g. <tt>C:/Dev/bootstrap</tt>)

+

*** You can create a new workspace (e.g. <tt>Mylyn-Work</tt>)

−

* Launching with this launch configuration will give you a second workbench with Mylyn. This workbench will be created based on the target platform (the workbench you're launching from) and the plugins in <tt>C:/Dev/build-3.3</tt>.

+

−

* Do your development in the runtime workspace (<tt>C:/Dev/workspace</tt>).

+

Launching with this launch configuration will give you a second workbench with Mylyn. This workbench will be created based on the target platform (the workbench you're launching from) and the installed plugins. This workspace needs to be setup following the steps under [[#Setup]]:

−

* Whenever your changes make it into HEAD that you would like to use, close your runtime workspace (<tt>C:/Dev/workspace</tt>), update from CVS in the build workspace (<tt>C:/Dev/build-3.3</tt>), and then re-launch your runtime workspace.

+

+

* [[#Checkout]]

+

* [[#Target_Environment]]

+

* [[#API_Baseline]]

+

* [[#Markers]]

+

* [[#JUnit_Tests]]

+

+

Do your development in the Mylyn-Work workspace. Whenever your changes make it into master that you would like to use, close your Mylyn-Work workspace, pull from Git in the Mylyn-Bootstrap workspace, and then re-launch your Mylyn-Work workspace.

Notes:

Notes:

Line 225:

Line 254:

* You must have two distinct workspaces, you can't bootstrap into the same workspace as you launch from.

* You must have two distinct workspaces, you can't bootstrap into the same workspace as you launch from.

* It is possible to run in debug mode so that the changes apply to the workspace immediately after synch, but this can cause problems with the running workspace if classes change or go missing. This is because the hot-swap virtual machine can only change method bodies, not class definitions.

* It is possible to run in debug mode so that the changes apply to the workspace immediately after synch, but this can cause problems with the running workspace if classes change or go missing. This is because the hot-swap virtual machine can only change method bodies, not class definitions.

−

−

=== Self-hosting for Eclipse 3.7===

−

The following is an example of how to set up a bootstrap workspace environment, using Eclipse 3.7 on Mac OS. The result is an folder with the following three workspaces:

−

* Mylyn-Bootstrap

−

* Mylyn-Work

−

* Mylyn-Runtime

−

−

Please follow the steps:

−

−

* install Eclipse ( I use Classic 3.7)

−

* start Eclipse and create an Workspace called Mylyn-Bootstrap an an folder you want<br> (I use <home>/Eclipse/Mylyn-Bootstrap)

−

* Import the Install Software Items from File Mylyn-Bootstrap.p2f

−

* Import Team Project Set MylynDependencies.psf

−

* Change the path to the Default Repository Folder in the Preferences to point to the Mylyn-Bootstrap Workspace

−

* Switch to the Git Repository Exploring Perspective and Clone the following Git Repositories<br> change xxx with your userid

* Import Projects… from the Git Repository Exploring Perspective and add an new Working Set "Mylyn"

−

* Set the API Baseline

−

* Set the Java Code Formater to {workspace}/org.eclipse.mylyn.incubator/org.eclipse.mylyn.ide.dev/developer/mylyn-settings-formatter.xml

−

* import preferences markers.epf

−

* do personal settings (like had or *.launch configurations-- Mylyn-Head)

−

−

Now the bootstrap workspace is finished.<br><br> Here how to setup the working workspace.

−

* start the run or debug configuration from the Mylyn-Bootstrap (this creates the Mylyn-Work folder).

−

* Quit the new workspace and copy the files repositories.xml.zip and tasks.xml.zip from the old workspace ../.metadata/.mylyn to the new Mylyn-Work/.metadata/.mylyn if you want to migrate your Repositories, Tasks and Querys

−

* restart the workspace and Change the path to the Default Repository Folder in the Preferences to point to the Mylyn-Work Workspace

−

* Import Team Project Set MylynDependencies.psf

−

* Change the path to the Default Repository Folder in the Preferences to point to the Mylyn-Bootstrap Workspace

−

* Switch to the Git Repository Exploring Perspective and Clone the following Git Repositories<br> change xxx with your userid

Now the work workspace is finished.<br><br> Set up the runtime workspace as you need (maybe you migrate this form a previous version)

== Contributors ==

== Contributors ==

Line 292:

Line 265:

* Use Bugzilla for all of your communication. This helps committers track the contribution.

* Use Bugzilla for all of your communication. This helps committers track the contribution.

* Before setting out to contribute to a bug report, post on the bug report describing your intention. This helps committers guide the contribution and avoids problems with patches going stale due to related work being done concurrently.

* Before setting out to contribute to a bug report, post on the bug report describing your intention. This helps committers guide the contribution and avoids problems with patches going stale due to related work being done concurrently.

−

* For contribution ideas see the list of [https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=Mylyn&long_desc_type=allwordssubstr&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&keywords_type=allwords&keywords=helpwanted&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailtype1=substring&email1=&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0= helpwanted bugs] to find one that interests you, file a new bug of your own, or email mylyn-dev for ideas.

+

* For contribution ideas see [[#Individual_Contributors]] to find an enhancement that interests you, file a new bug of your own, or email mylyn-dev for ideas.

=== Tips ===

=== Tips ===

−

Following these steps will help get your patches applied more quickly.

+

Following these steps will help get your patches applied more quickly.

−

# Before implementing the functionality post a brief proposal of the implementation and UI changes/additions and get a committer's feedback. The committer should be either the [http://www.eclipse.org/mylyn/contributors/ component owner] or [[Mylyn#Mentors|your mentor]].

+

# Before implementing the functionality post a brief proposal of the implementation and UI changes/additions and get a committer's feedback. The committer should be either the [http://www.eclipse.org/mylyn/contributors/ component owner].

# After that's applied iterate on the UI proposal if needed and the post the patch to the UI.

# After that's applied iterate on the UI proposal if needed and the post the patch to the UI.

Line 306:

Line 279:

We use votes in order to track the general interest in a particular bug. Bugs with more votes are more likely to get fixed. However, we also have numerous "[connector]" bugs that are open, but out of the scope of the project. We encourage all in the community to vote for bugs, since it helps contributors prioritize work. If you notice a vote from a committer on a bug, the likely reason is that they would like to see the fix as well, even though the current priorities may mean that it is not planned for the near future (e.g. a UI enhancement while API is being prioritized).

We use votes in order to track the general interest in a particular bug. Bugs with more votes are more likely to get fixed. However, we also have numerous "[connector]" bugs that are open, but out of the scope of the project. We encourage all in the community to vote for bugs, since it helps contributors prioritize work. If you notice a vote from a committer on a bug, the likely reason is that they would like to see the fix as well, even though the current priorities may mean that it is not planned for the near future (e.g. a UI enhancement while API is being prioritized).

−

=== Patches ===

+

=== Contributions ===

−

In order to make your patch get applied as quick as possible, we recommend the following workflow:

+

In order to make your contributions get applied as quick as possible, we recommend the following workflow:

# Comment on the corresponding bug, asking whether a committer or another contributor has any suggestions for the implementation approach.

# Comment on the corresponding bug, asking whether a committer or another contributor has any suggestions for the implementation approach.

# After a committer iterates with you on the design, prefix the summary of the bug report with "[patch]", and wait for review.

+

# After a committer iterates with you on the design, submit the proposed change to Gerrit and prefix the summary of the bug report with "[review]".

−

# Note that the review process might involve iterating on the patch, especially if there are UI changes or additions involved.

+

# Note that the review process might involve iterating on the change, especially if there are UI changes or additions involved.

−

'''Creating'''

+

See below on more details how to work with Gerrit.

−

* Each patch should correspond to a single bug report, and a single patch should be made for each set of changes to be reviewed.

+

−

* A task context should be attached to each patch to make applying and evolving it easier.

+

−

* 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 the changes are tracked per task.

+

−

* 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 <tt>org.eclipse.mylyn/mylyn-settings-formatter.xml</tt> from the org.eclipse.mylyn project into <i>Window -> Preferences -> Java -> Code Style -> Formatter</i>. Format code using Eclipse's formatter (Ctrl+Shift+F) and ensure that no have been added.

+

−

* Add an <tt>@author</tt> tag to each class that you create or make significant modification to, placed below any existing author tags and indicating the bug, e.g.: <tt>@author Rob Elves (bug 160315)</tt>

+

−

* Ensure that there is no console output. For logging errors use <tt>org.eclipse.mylyn.monitor.core.StatusHandler</tt>.

+

−

* If tempted to copy code from either Mylyn or any other part of Eclipse, please first comment on the bug that you intend to do so. The need to copy code is often indicative of the need for us to provide additional modularity, and creates a maintenance burden for the project. If you do copy code, please put an <tt>@see</tt> link in the Javadoc for the method or class that has the copied code.

+

−

* When creating patches with Git, see [[Git_for_Committers#Generating_patches_for_Bugzilla]] or use EGit [[EGit/User_Guide#Creating_Patches]]

+

−

+

−

'''Submitting'''

+

−

* Ensure there are no build errors, warnings, and that org.eclipse.mylyn.tests.AllTests passes.

+

−

* Do not include binary files such as GIF icons in the patch, they need to be attached separately.

+

−

* 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 select ''Save to clipboard''.

+

−

* In the ''Attachments'' section of the ''Task Editor'' select ''Attach File...'' and use ''Clipboard'' as the source. Check off the ''Patch'' and ''Attach Context'' checkboxes in this wizard page.

+

−

* Add a description of issues addressed and comment on what testing was done to validate it (e.g. unit test coverage, manual tests performed). Also indicate any changes made to the existing UI in the comment (e.g. reordering of menu actions). Also indicate if patch is intended to resolve bug report or further work is required.

Mylyn uses the Eclipse code conventions. See [[#Links]] for references.

−

Tags: Mylyn uses the following tags in the code:

+

=== Graphics ===

−

* TODO: The following code needs to be reviewed.

+

−

* TODO API: Indicates that a method or class needs to be reviewed.

+

−

* TODO API x.y: This API is going to change for version x.y. Should include a description how it is going to change.

+

−

* TODO e3.4: Make a change in the future specific to an Eclipse version.

+

−

* XXX: The implementation uses a temporary work around that should be replaced by a proper solution in the future.

+

−

* XXX SDK: The code uses internals of the Eclipse platform.

+

−

* FIXME: Should only be used in very rare cases as a reminder that the marked code does not work as expected. Code marked as FIXME should not be distributed in a release.

+

−

* FIXME REVIEW: Review the code before the next version is released

+

−

==== Resources ====

+

If contributing a feature with icons or other graphics feel free to ask a committer to generate the graphic for you. If interested in contributing graphics you can find all of the source files (e.g. Photoshop) here: <code>mylyn/graphics/ui</code>.

If contributing a feature with icons or other graphics feel free to ask a committer to generate the graphic for you. If interested in contributing graphics you can find all of the source files (e.g. Photoshop) here: <code>mylyn/graphics/ui</code>.

+

* Register an Eclipse.org account at [https://dev.eclipse.org/site_login/createaccount.php dev.eclipse.org]. The same account is used for [https://bugs.eclipse.org/bugs Bugzilla] and [https://git.eclipse.org/r Gerrit].

Gerrit is added as remote to the local clone of a Mylyn Git repository. You can either configure the "origin" remote to use the Gerrit URL or you can add another remote. For example, the <code>.git/config</code> file for the Mylyn Tasks git repository would specify this additional remote (replace spingel with your username):

If you are not able to connect to git.eclipse.org through SSH on port 29418 you can instead [https://git.eclipse.org/r/#settings,http-password setup a password for HTTP access]. In this case the url in the remote configuration needs to specify a different url:

Make sure you are using Git Client version 1.7.2 or later. Earlier versions might have problems connecting to the Gerrit Server.

+

+

Additionally, these settings are recommended in the <code>.git/config</code> to automatically generate the required Change-Id header when committing locally:

+

+

[gerrit]

+

createchangeid = true

+

+

==== Add Gerrit as a Task Repository ====

+

+

First install the Gerrit Mylyn connector using Install More Connectors from the New Task dialog.

+

+

After than you can add https://git.eclipse.org/r as a task repository in the Task Repositories view and create queries to bring your code reviews into your task list.

+

+

==== Create a Code Review ====

+

+

* Create a topic branch

+

git checkout -t origin/master -b bug#123-my-topic-branch

+

* Commit to the branch. Ensure that a Change-Id header is included in the commit message.

+

* Submit the code review

+

git push gerrit

+

+

==== Update a Code Review ====

+

+

* Check out the topic branch

+

* Update to the latest master

+

git pull

+

* Commit changes

+

git commit -a --amend

+

* Update code review

+

git push gerrit

+

+

==== Squash Commits ====

+

+

Gerrit creates one code review per commit. If you committed multiple times you can always [http://eclipsesource.com/blogs/2011/10/18/git-tip-reviewing-and-committing-a-branch-full-of-changes/ squash commits later using interactive rebase], e.g. to merge the last two commits into one commit use this command:

+

+

$ git rebase -i HEAD~2

+

+

This opens an editor to modify the commit history. If you change ''pick''in the second line of the editor to ''fixup'' that commit will be merged with the previous commit when you exit the editor.

+

+

==== Merging Contributions ====

+

+

The Eclipse IP process requires that all contributions that exceed 250 lines are reviewed in a CQ (contributors questionar). [http://wiki.eclipse.org/Development_Resources/Handling_Git_Contributions Smaller contributions] can be merged directly once the contributor asserts the following on the Gerrit review or corresponding Bugzilla bug:

+

+

# I authored 100% of the content that I am contributing.

+

# I have the rights to donate the content to Eclipse.

+

# I contribute the content under the EPL.

+

+

=== Submitting Patches ===

+

+

If you are unable to submit contributions through a Gerrit code review you can alternatively attach patches to Bugzilla bugs. Please note that Gerrit is the preferred mechanism for handling contributions.

+

+

'''Creating'''

+

* Each patch should correspond to a single bug report, and a single patch should be made for each set of changes to be reviewed.

+

* A task context should be attached to each patch to make applying and evolving it easier.

+

* 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 the changes are tracked per task.

+

* Before creating a new JUnit test class class check the components test suite for similar test cases (e.g. AllTasklistTests).

+

* Add an <tt>@author</tt> tag to each class that you create or make significant modification to, placed below any existing author tags, e.g.: <tt>@author Rob Elves</tt>

+

* Ensure that there is no console output.

+

* If tempted to copy code from either Mylyn or any other part of Eclipse, please first comment on the bug that you intend to do so. The need to copy code is often indicative of the need for us to provide additional modularity, and creates a maintenance burden for the project. If you do copy code, please put an <tt>@see</tt> link in the Javadoc for the method or class that has the copied code.

+

+

'''Submitting'''

+

* Ensure there are no build errors, warnings, and that tests pass.

+

* Commit your changes to your local Git repository

+

* Drag and drop the commit from the History view to the task editor. This will open the attach wizard. Alternatively you can create the patch manually:

+

** For creating patches with Git, see [[Git_for_Committers#Generating_patches_for_Bugzilla]] or use EGit [[EGit/User_Guide#Creating_Patches]]

+

** In the ''Attachments'' section of the ''Task Editor'' select ''Attach File...'' and use ''Clipboard'' as the source.

+

* On the preview page verify that:

+

** Patches are rooted at the root of the Git repository

+

** Patches only contain relevant changes

+

* Check off the ''Patch'' and ''Attach Context'' checkboxes in this wizard page.

+

* Add a description of issues addressed and comment on what testing was done to validate it (e.g. unit test coverage, manual tests performed). Also indicate any changes made to the existing UI in the comment (e.g. reordering of menu actions). Also indicate if patch is intended to resolve bug report or further work is required.

Integration tests run against the [http://git.eclipse.org/c/mylyn/org.eclipse.mylyn.all.git/ Git integration build] repository that includes all sub-projects as submodules. Integration tests are triggered by the [https://hudson.eclipse.org/hudson/job/mylyn-release/ mylyn-release job].

Integration tests run against the [http://git.eclipse.org/c/mylyn/org.eclipse.mylyn.all.git/ Git integration build] repository that includes all sub-projects as submodules. Integration tests are triggered by the [https://hudson.eclipse.org/hudson/job/mylyn-release/ mylyn-release job].

Line 538:

Line 579:

The full suite of repository tests is only run on the most recent Eclipse platforms. Running the full suite is expensive and a Bugzilla or Trac specific test that fails on Eclipse 3.5 is very likely to also fail on Eclipse 3.7.

The full suite of repository tests is only run on the most recent Eclipse platforms. Running the full suite is expensive and a Bugzilla or Trac specific test that fails on Eclipse 3.5 is very likely to also fail on Eclipse 3.7.

−

==== Release Jobs ====

+

'''Release Jobs'''

Release and snapshot artifacts created by release jobs are published to download.eclipse.org.

Release and snapshot artifacts created by release jobs are published to download.eclipse.org.

Line 548:

Line 589:

mylyn-release - master branch

mylyn-release - master branch

−

=== Feature Maturity ===

+

=== Maven ===

−

Mylyn features vary in UI maturity and availibility of support. The following is a guideline for what it takes to move from experimentation through to maturity. (Note that this is partially based on the [http://www.eclipse.org/projects/dev_process/development_process.php#6_2_3_Incubation Eclipse project lifecycle] and could converge further with that lifecycle if Mylyn were split into a separate incubation project or subprojects.)

+

The Mylyn build is based on Maven/Tycho. The minimum required Maven version is 3.0.

−

'''Mature''': packaged Eclipse downloads and available via main update site

+

* The <code>org.eclipse.mylyn/org.eclipse.mylyn-parent</code> module specifies a parent pom with common settings. This pom is published to the [http://mirrors.ibiblio.org/pub/mirrors/eclipse/mylyn/maven/snapshots/ Mylyn Maven repository].

+

* The <code>org.eclipse.mylyn/org.eclipse.mylyn-target</code> module specifies a target definitions. These are published to the [http://mirrors.ibiblio.org/pub/mirrors/eclipse/mylyn/maven/snapshots/ Mylyn Maven repository].

−

* UI quality: Eclipse SDK features have set a very high quality and UI consistency bar that needs to be met in order to make it possible to improve users' productivity with Eclipse.

+

==== Builds ====

−

* UI simplicity: the Mylyn project's goal is to simplify and streamline the user experience. A simple and self-evident UI also helps ensure a manageable support burdeon on the component.

+

mvn package

−

* Availability of support: the feature must have an owner or organization with a long-term commitment to the quality of the feature and the ability to provide responsive support for feedback on that feature.

+

To skip execution of tests use <code>-Dmaven.test.skip=true</code>

−

* Responsiveness to feedback: the feature owner and other contributors must process and prioritize user feedback and respond to the highest priority needs in a timely manner (e.g. blockers and critical bugs need to be fixed within one release of being submitted, key enhancements help the feature evolve to meet users' needs).

+

==== Tests ====

−

'''Incubation and Sandbox''': available via the ''Incubation'' update site

+

To run tests invoke the following command:

−

* Unsupported components used for experimentation and not intended for daily use.

+

mvn integration-test

−

* Community interest and contributions determine which experimental features move from the Sandbox into Extras.

* Make sure to update <code>mylyn-iplog.csv</code> with an entry for each bug that is resolved by patch. Note that each patch should not contain more than 250 lines of code of unique and seprately usable functionality. For larger patches we need to invoke the IP Review process.

+

The [[Mylyn/Release_Howto|Release Howto]] describes how to build and publish official Mylyn releases.

−

* Contributors frequently write quick patches in order to get something working for them. It is the responsibility of the committer to either encourage the contributor to improve the modularity and test coverage of the patch or to do those themselves if this aligns with the projects' priorities. Failing to do so can reduce the overall quality of the code and failing to get sufficient test coverage reduces our ability to evolve the code.

+

==== Profiles ====

+

+

The build defines profiles to build Mylyn against different targets. Profiles can be activated by passing <code>-P<profile></code> to mvn.

+

+

* <code>implicit-target</code> - build against nightly repositories, this is the default

+

* <code>explicit-target</code> - build against a target definitions in <code>org.eclipse.mylyn/org.eclipse.mylyn-target</code>, needs to be activated through property <code>-Dexplicit-target</code>

Properties control certain aspects of the build such as execution of tests or optional analysis of source code. Properties can be set by passing <code>-D<property>=<value></code> to mvn. All properties are initialized to sensible default values and are optional.

+

+

* <code>tycho-version</code> - version of Tycho to use for building

+

* <code>analysis.skip</code> - set to false to run code analysis (default: true)

+

* <code>test.skip</code> - set to false to run tests (default: ${maven.test.skip})

+

* <code>sign.skip</code> - set to false to run code signing (default: true)

+

* <code>pack.skip</code> - set to false to run pack repositories (default: false)

* TODO API x.y: This API is going to change for version x.y. Should include a description how it is going to change.

+

* TODO e3.4: Make a change in the future specific to an Eclipse version.

+

* XXX: The implementation uses a temporary work around that should be replaced by a proper solution in the future.

+

* XXX SDK: The code uses internals of the Eclipse platform.

+

* FIXME: Should only be used in very rare cases as a reminder that the marked code does not work as expected. Code marked as FIXME should not be distributed in a release.

+

* FIXME REVIEW: Review the code before the next version is released

−

=== Creating new plug-ins ===

+

==== Creating new plug-ins and features ====

File a bug that describes the purpose of the new plug-ins and the proposed names. Then add an item to the weekly meeting agenda to discuss the request with other committers. Once consensus has been reached follow the steps below.

File a bug that describes the purpose of the new plug-ins and the proposed names. Then add an item to the weekly meeting agenda to discuss the request with other committers. Once consensus has been reached follow the steps below.

−

Checklist for creating a new plug-in:

+

To retain consistency of layout and settings, new projects should always be created by copying an existing project rather than creating plug-in or feature projects from scratch.

−

# Copy an existing project in your workspace to retain all standard settings

# Edit <code>pom.xml</code>, <code>.project</code> and <code>META-INF/MANIFEST</code> to reflect the new bundle id

−

* Check out www/mylyn as a project

+

# List the new bundle as a module in the parent pom to include it in the build

+

# Use Import Projects from the popup menu in the Git Repositories view to add the project to the workspace

−

You need to be a member of <code>mylyn-home</code> to commit changes to the website.

+

For plug-ins these additional steps should be considered:

−

=== Building a distribution ===

+

# Add bundle to feature

−

* Check out the org.eclipse.mylyn.releng project.

+

# Add source bundle to SDK feature

−

* Customize the build to your local environment following instructions in the README.txt file.

+

−

* Run <code>ant</code> to build release artifacts.

+

−

The [[Mylyn/Release_Howto|Release Howto]] describes how to build and publish official Mylyn releases.

+

For features these additional steps should be considered:

−

=== Creating New Components ===

+

# Add feature to site

−

Most sub-projects host a framework component and one or more reference implementations. When new code is brought into Mylyn it may be added as a sub-project, sub-sub-project or as a component of an existing project. The right organisational structure depends on the needs of the development community and the scope and process of the existing projects. Criteria that could qualify a component to be split out as a separate project:

Contributions are a key part of evolving Mylyn. All committers should encourage and prioritize contributions.

−

* The committer set of the component is not a subset of the committer set of the framework project.

+

−

* A component wants to release more frequently than its framework project, i.e. it follows it's own project plan.

+

==== Applying Patches ====

−

* A component publishes its own APIs and its scope and community are significant that it requires its separate management structure such as a Bugzilla product, news group etc.

+

+

* Note that each patch should not contain more than 250 lines of code of unique and seprately usable functionality. For larger patches we need to invoke the IP Review process.

+

* Contributors frequently write quick patches in order to get something working for them. It is the responsibility of the committer to either encourage the contributor to improve the modularity and test coverage of the patch or to do those themselves if this aligns with the projects' priorities. Failing to do so can reduce the overall quality of the code and failing to get sufficient test coverage reduces our ability to evolve the code.

+

+

When applying a patch follow these steps:

+

+

'''Git'''

+

* Enter the name of the contributor as the author of the commit

+

* Encourage the contributor to update the patch into state where it can be applied unaltered.

+

* If you need to make addtional changes that are non-trivial (e.g., copyright header fixes) commit the unaltered patch first and then make another commit with your changes.

+

** If absolutely necessary, a task-branch can be used to group commits and improve traceability otherwise commit messages should be sufficient to associate bugs with commits.

+

* All files altered by a contributor must have a note in the copyright header and should have an @author tag if a change was significant.

+

* If several authors have worked on a commit consider adding ''Co-authored-by'' headers to the commit message for each author.

You need to be a member of the <code>mylyn</code> group to commit changes to the website.

== Incubator ==

== Incubator ==

Line 634:

Line 720:

The following experimental views can be opened via the ''Experimental'' view category or accessed via the ''Tasks -> Experimental'' preference page.

The following experimental views can be opened via the ''Experimental'' view category or accessed via the ''Tasks -> Experimental'' preference page.

−

−

* '''Task Trim Widget''': Shows the active task.

* '''Context Search''': Automatically finds and displays elements that are structurally related to landmarks in the active . These elements become part of the task context and have a predicted degree-of-interest.

* '''Context Search''': Automatically finds and displays elements that are structurally related to landmarks in the active . These elements become part of the task context and have a predicted degree-of-interest.

Project Structure

The Mylyn project is structured into sub-projects that address different areas of Application Life-cycle Management. Please see Mylyn/Charter for the top-level project charter.

Artifacts are published in a number of Mylyn/Repositories. The main repository aggregates sub-projects that participate in Mylyn releases. The participating projects are listed in the project plan. The main Mylyn update site features are mature components that are supported by the Mylyn project committers and may be distributed as part of the Eclipse Downloads.

Sub-projects are encouraged to provide a framework component and reference implementations called Connectors that extend Mylyn to different task management systems and focus the artifacts that you work with when you activate a task (formerly called Bridges).

Feature Maturity

Mylyn features vary in UI maturity and availibility of support. The following is a guideline for what it takes to move from experimentation through to maturity. (Note that this is partially based on the Eclipse project lifecycle and could converge further with that lifecycle if Mylyn were split into a separate incubation project or subprojects.)

Mature: packaged Eclipse downloads and available via main update site

UI quality: Eclipse SDK features have set a very high quality and UI consistency bar that needs to be met in order to make it possible to improve users' productivity with Eclipse.

UI simplicity: the Mylyn project's goal is to simplify and streamline the user experience. A simple and self-evident UI also helps ensure a manageable support burden on the component.

Availability of support: the feature must have an owner or organization with a long-term commitment to the quality of the feature and the ability to provide responsive support for feedback on that feature.

Responsiveness to feedback: the feature owner and other contributors must process and prioritize user feedback and respond to the highest priority needs in a timely manner (e.g. blockers and critical bugs need to be fixed within one release of being submitted, key enhancements help the feature evolve to meet users' needs).

Incubation: available via the nightly update site

High quality components that meet most but not all of the above criteria. To graduate, sufficient community feedback must be available on the quality and usability of the component (e.g. 100+ resolved bugs) and committers must vote to determine whether component meets the UI quality and simplicity guidelines.

Sandbox: available via the Incubation update site

Unsupported components used for experimentation and not intended for daily use.

Community interest and contributions determine which experimental features move from the Sandbox into Extras.

Creating New Components

Most sub-projects host a framework component and one or more reference implementations. When new code is brought into Mylyn it may be added as a sub-project, sub-sub-project or as a component of an existing project. The right organisational structure depends on the needs of the development community and the scope and process of the existing projects. Criteria that could qualify a component to be split out as a separate project:

A component requires incubation status (e.g. for parallel IP) but the framework project has already matured.

The committer set of the component is not a subset of the committer set of the framework project.

A component wants to release more frequently than its framework project, i.e. it follows it's own project plan.

A component publishes its own APIs and its scope and community are significant that it requires its separate management structure such as a Bugzilla product, news group etc.

Getting Started

The Mylyn project places a very high value on community contributions. This document is intended to help those interested in contributing to Mylyn. It communicates our conventions and discusses ways to get your contributions prioritized.

Individual Contributors

A significant portion of Mylyn contributions have been made by individuals wanting to make the tool or framework work better for them. There are several ways that individuals can get involved with the project:

Mentoring: if you are an experienced user, you can support newcommers by providing feedback using the community channels

Casual contribution: we have a large number of very valuable casual contributors who provide patches for their pet bugs, or enhancements that either they would find valuable or that they want to share with others. If you are interested but don't know where to start look first through the short list of bugday bugs, and then through the longer helpwanted list.

helpwanted bugs: a longer list of all bugs targeted at community contributions

Working towards commit rights: The Eclipse and Mylyn development processes make it easy to make regular contributions without requiring commit rights, but frequent contributors may be interested in earning commit rights. Commit rights come with a significant overhead of user support as well as the need to follow the project's priorities for contributions. They require you to participate in the planning and of the project, and allow you influence the direction of the tool and framework. If you are interested in becoming a committer we recommend letting one of the existing committers know so that they can mentor you and help build a trust relationship. It can also help to identify a separable component of the project that you are interested in taking responsibility for, since Mylyn commit rights are assigned per-component.

Integrators and Vendors

Those building both closed and open source tools on top of Mylyn may be interested in evolving the Mylyn APIs to ensure that that the framework meets their needs. We welcome such contributions just as we welcome individuals making improvements to the tool, since they help make Mylyn a better framework for all. The Individual Contributor points above apply to integrators and vendors interested in contributing or earning commit rights. In addition, the following tips may be of interest:

If interested in exploring Mylyn integration, consider dialing into the our weekly call and adding an agenda item on the Mylyn Meetings page.

Vendors are welcome, so make yourself known. We recommend using your company name for Bugzilla email addresses. If you have a product built on Mylyn and need a bug fixed, we recommend voting for it with that email address. The Mylyn project prioritizes bugs according to how much overall benefit they will have to users, and as such commercial integrations are an important part of that prioritization. If the bug does not fit with the project's priorities we will encourage you to provide a patch.

Consider making a bug titled "support integration with <your tool>". We use these bugs for discussing integration issues particular to a specific tool or technology and leave them open for ongoing API or UI discussion needs.

Links

Workspace

The recommended way to work with Mylyn sources is by checking them out of Git. Doing this makes it easy to try the latest changes and work with patches and ensures that you can easily browse the source code and documenation using Eclipse's facilities.

Setup

Install Eclipse and get it configured for developing Java 5 applications.

To install additional JRE profiles or if you are unable to obtain a J2SE 1.5 installation install Add PDE/API Tools Environment Descriptions from the Eclipse project repository that corresponds to your Eclipse environment, e.g. http://download.eclipse.org/eclipse/updates/3.7

Checkout

The source code is hosted in Gerrit which is a code review system for Git. Each sub-project has a separate repository that is accessible through the git, ssh and https protocol. For anonymous access use git or https. Committers need to use ssh or https.

:pserver:dev.eclipse.org:/cvsroot/tools can be used for manual checkout

Target Environment

Mylyn depends on a number of libraries from other Eclipse projects. The org.eclipse.mylyn.releng project provides target environment definitions that specify all required dependencies. After following the steps under Checkout go to Window > Preferences and open the Target Platform page. Select one of the mylyn target definitions. Generally, mylyn-dev-base is the recommended choice.

mylyn-dev-base - Targets the lowest support Eclipse version. Includes sources and additional integration features for development.

mylyn-dev-latest - Targets the highest support Eclipse version. Includes sources and additional integration features for development.

mylyn-e* - Target defintions used by the build. May only contain the minimal requirements excluding sources.

API Baseline

An API baseline for the latest releases is available from the download archive. Follow these instructions to configure the API baseline in your workspace:

Extract a version of Eclipse Classic (SDK) to a directory that matches the version of your current target platform

Extract the Mylyn API baseline zip archive to the eclipse/plugins directory from the extraced SDK

Add the baseline under Windows > Preferences > Plug-in Development > API Baselines pointing to the eclipse/plugins directory from the extracted SDK

Markers

The general policy is that plug-ins should not have any errors or warning markers since these indicate potential problems or API insufficiencies. In practice, we do not have the capacity to address all warnings or the cost outweighs the benefit or warnings result out of intentional design decisions, e.g. usage of deprecated APIs for
maintaining backwards compatibility.

To reduce the number of warnings we have established the following policies for usage of internal packages:

Plug-ins are allowed to use internals within the boundaries of their component (e.g. o.e.m.bugzilla.ui may access internals of o.e.m.bugzilla.core). We have generally allowed that through x-friends relationships in plug-in manifests.

It's generally okay to use provisional APIs. We have made these accessible through classpath filters: Project Properties > Java Build Path > Libraries > Plug-in Dependencies > Access rules. It's common that plug-ins have a rule to make org/eclipse/mylyn/internal/provisional/** accessible.

In cases where platform internals need to be accessed due to a lack of API it's okay to make the specific classes or packages accessible. These cases should be documented on bug 233055.

Test plug-ins are allowed to use all internals.

Additionally, it is recommend to create custom filters in the workspace to hide remaining warnings that will not get addressed in the short time. Filter can be configured through the view menu of the Markers view.

JUnit Tests

Each component has it's own All<Component>Tests suite. If not familiar with running PDE JUnit tests, refer to the Eclipse Documentation.

Tests that connect to repositories require a $HOME/.mylyn/credentials.properties file that specifies authentication information. The file needs to have the following content:

user: <user>
pass: <pass>

For <user> use tests@mylyn.eclipse.org. For <pass> use mylyntest. If you have any trouble making this work email mylyn-dev@eclipse.org.

Add the following to the test configuration under Arguments -> VM Arguments: -enableassertions -Xmx384M

Test suites in org.eclipse.mylyn.tests:

AllTests: all automatic tests, should always pass, run as a JUnit Plug-in Test

AllHeadlessStandaloneTests: do not require workbench, can run as JUnit Test, subset of AllTests

Use Import Projects from the Git Repository Exploring Perspective to add the projects to your workspace

Create a new Launch Configuration:

SelectRun -> Run... -> create a new Eclipse Application.

Call the application Mylyn Work.

On the Main tab, set the Location

You can use an existing workspace

You can create a new workspace (e.g. Mylyn-Work)

Launching with this launch configuration will give you a second workbench with Mylyn. This workbench will be created based on the target platform (the workbench you're launching from) and the installed plugins. This workspace needs to be setup following the steps under #Setup:

Do your development in the Mylyn-Work workspace. Whenever your changes make it into master that you would like to use, close your Mylyn-Work workspace, pull from Git in the Mylyn-Bootstrap workspace, and then re-launch your Mylyn-Work workspace.

Notes:

The launching workspace will typically consume very little memory.

Working in bootstrap mode means you have the source code checked out at least twice, once to bootstrap Mylyn, and once to actually develop.

You must have two distinct workspaces, you can't bootstrap into the same workspace as you launch from.

It is possible to run in debug mode so that the changes apply to the workspace immediately after synch, but this can cause problems with the running workspace if classes change or go missing. This is because the hot-swap virtual machine can only change method bodies, not class definitions.

Contributors

All contributions to Mylyn need to be made using Mylyn since it links source changes to tasks and contexts, making open development and collaboration easier. Using Mylyn ensures that:

All Bugzilla reports have a corresponding task context, making them easy to reopen or pick up by you and by others.

All commits correspond to a single Bugzilla report, making it easy to navigate from changes to bugs.

Getting Started

Use Bugzilla for all of your communication. This helps committers track the contribution.

Before setting out to contribute to a bug report, post on the bug report describing your intention. This helps committers guide the contribution and avoids problems with patches going stale due to related work being done concurrently.

For contribution ideas see #Individual_Contributors to find an enhancement that interests you, file a new bug of your own, or email mylyn-dev for ideas.

Tips

Following these steps will help get your patches applied more quickly.

Before implementing the functionality post a brief proposal of the implementation and UI changes/additions and get a committer's feedback. The committer should be either the component owner.

After that's applied iterate on the UI proposal if needed and the post the patch to the UI.

Note that the smaller you make patches and the more focused they are on individual and well-tested units of functionality the more quickly they will get applied.

Voting

We use votes in order to track the general interest in a particular bug. Bugs with more votes are more likely to get fixed. However, we also have numerous "[connector]" bugs that are open, but out of the scope of the project. We encourage all in the community to vote for bugs, since it helps contributors prioritize work. If you notice a vote from a committer on a bug, the likely reason is that they would like to see the fix as well, even though the current priorities may mean that it is not planned for the near future (e.g. a UI enhancement while API is being prioritized).

Contributions

In order to make your contributions get applied as quick as possible, we recommend the following workflow:

Comment on the corresponding bug, asking whether a committer or another contributor has any suggestions for the implementation approach.

After a committer iterates with you on the design, submit the proposed change to Gerrit and prefix the summary of the bug report with "[review]".

Note that the review process might involve iterating on the change, especially if there are UI changes or additions involved.

See below on more details how to work with Gerrit.

Writing Tests

Writing tests along with patches is key to ensuring that it is possible for committers to maintain the new functionality added by the patch. When writing tests look for the All<component>Tests class in the tests plug-in for that component, identify a test that is similar to the functionality that you are adding, and use that test as an example of how to add additional coverage. Tests can sometimes take longer to write then the change itself, but a committer will always be willing to assist you in designing the test or extending the mock test harness to make it easier to write.

The key things to ensure is that your test covers is the addition or change to the existing functionality. For API changes it is often sufficient to have the public method covered. When writing tests for UI components, the simplest way of testing will often involve a combination of unit and black-box testing, for example, relying on other parts of the Mylyn UI to be set up (e.g. the Task List view). Consider the case of adding functionality for pre-selecting a repository in the New Task dialog, writing a test can take the following form (refer to NewTaskWizardRepositorySelectionTest):

Create a mock repository

Add a task to the mock repository

Set the selection on the Task List (new functionality uses this selection)

Invoke the wizard and assert that the selection was set correctly on the viewer (wizard is a black box, all we care about is the contents of the viewer)

Dispose the wizard dialog, remove the mock repository and the mock task

When writing UI tests note that asynchrous updates, such as refresh, can make testing challenging. Note that several UI components have a method on them to set synchronous execution for the purpose of testing, and if such a method is lacking it can be added.

Code

Graphics

If contributing a feature with icons or other graphics feel free to ask a committer to generate the graphic for you. If interested in contributing graphics you can find all of the source files (e.g. Photoshop) here: mylyn/graphics/ui.

Add Gerrit as a Git Remote

Gerrit is added as remote to the local clone of a Mylyn Git repository. You can either configure the "origin" remote to use the Gerrit URL or you can add another remote. For example, the .git/config file for the Mylyn Tasks git repository would specify this additional remote (replace spingel with your username):

If you are not able to connect to git.eclipse.org through SSH on port 29418 you can instead setup a password for HTTP access. In this case the url in the remote configuration needs to specify a different url:

This opens an editor to modify the commit history. If you change pickin the second line of the editor to fixup that commit will be merged with the previous commit when you exit the editor.

Merging Contributions

The Eclipse IP process requires that all contributions that exceed 250 lines are reviewed in a CQ (contributors questionar). Smaller contributions can be merged directly once the contributor asserts the following on the Gerrit review or corresponding Bugzilla bug:

I authored 100% of the content that I am contributing.

I have the rights to donate the content to Eclipse.

I contribute the content under the EPL.

Submitting Patches

If you are unable to submit contributions through a Gerrit code review you can alternatively attach patches to Bugzilla bugs. Please note that Gerrit is the preferred mechanism for handling contributions.

Creating

Each patch should correspond to a single bug report, and a single patch should be made for each set of changes to be reviewed.

A task context should be attached to each patch to make applying and evolving it easier.

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 the changes are tracked per task.

Before creating a new JUnit test class class check the components test suite for similar test cases (e.g. AllTasklistTests).

Add an @author tag to each class that you create or make significant modification to, placed below any existing author tags, e.g.: @author Rob Elves

Ensure that there is no console output.

If tempted to copy code from either Mylyn or any other part of Eclipse, please first comment on the bug that you intend to do so. The need to copy code is often indicative of the need for us to provide additional modularity, and creates a maintenance burden for the project. If you do copy code, please put an @see link in the Javadoc for the method or class that has the copied code.

Submitting

Ensure there are no build errors, warnings, and that tests pass.

Commit your changes to your local Git repository

Drag and drop the commit from the History view to the task editor. This will open the attach wizard. Alternatively you can create the patch manually:

In the Attachments section of the Task Editor select Attach File... and use Clipboard as the source.

On the preview page verify that:

Patches are rooted at the root of the Git repository

Patches only contain relevant changes

Check off the Patch and Attach Context checkboxes in this wizard page.

Add a description of issues addressed and comment on what testing was done to validate it (e.g. unit test coverage, manual tests performed). Also indicate any changes made to the existing UI in the comment (e.g. reordering of menu actions). Also indicate if patch is intended to resolve bug report or further work is required.

Committers

Participation

Read the newsgroup regularly, and respond to posts in their area of expertise.

Respond to mylyn-dev email in their area of expertise.

Watch and update all wiki pages related to components that they contribute to.

Communication

Mylyn committers are required to follow these communication guidelines. Our philosophy is that the user is always right, even if it takes time to figure out how or why they are right. Our project thrives on the feedback of users, whether they are seasoned experts or newbies. Feedback defines how the tool should work, how it should be simplified, and how it should evolve.

All feedback contains information, and it is the responsibility of committers to turn that information into actions. This can mean improving the implementation, simplifying the workflow, clarifying the documentation, or noting a duplicate request. Making the actions we take clear helps communicate this philosophy to our growing user community and encourages high-quality feedback.

If users do not provide enough information or do not take the time to provide accurate information, they should be prompted to provide the necessary details. If they do not do so in a timely manner, the feedback is incomplete and can be resolved without taking action.

Show respect to others in the community, whether they are making correct or incorrect assumptions about the tool or technology. When someone makes incorrect assumptions it is because we have not done our job well enough, or because the platforms we build on are making it hard for us to do our job well enough. Identifying those cases is important so that we can provide feedback to those platforms and find work-arounds.

Never turn feedback or discussion away by flaming, being condescending, short, or insulting in any community communication forum. Forms of humor that work for face-to-face communication, such as sarcasm, are usually best avoided because they can result in misinterpretation, especially when there is a language or cultural barrier.

Handling Inappropriate Communication

In the vast majority of cases, following the above guidelines has lead to the high quality communication that our user and contributor community has thrived on. However, the openness of our communication channels has been abused in the past. These scenarios are typically marked by overly opinionated, non-technical and insulting posts on bugs in and in other forums. The communication may have technical elements or technical points, but the points are communicated in an overly opinionated way with a disregard for the opinions of others involved in the dialog. If encountering such communication, make sure to read the Wikipedia Entry on Flaming, especially the "Causes of flaming" section.

Note that invoking the process listed below should be the exception, and not the rule. Projects with like-minded committers can experience the Groupthink bug, which is why high quality open communications channels are so important to helping the project evolve. However, abuse undoes the openness that we strive for by making the channels intimidating or unfriendly to newcommers. Follow these steps if you encounter such communication:

Make one or two attempts to steer the conversation back on a technical path.

If that doesn't address the problem, enter the following text as the third comment:

Bugzilla

Any user-reported bug should be resolved by one of: code improvements, documentation/FAQ improvements, or being marked a duplicate of another bug. All but the last require attaching a context.

Be judicious in marking bugs for LATER, because this typically communicates that the bug will never be resolved. Do this only if the bug does not fit in with the current scope of the project but is related to the mission. Otherwise mark P4/P5 and "helpwanted" to encourage a contribution that is not part of our current prioritization and plan.

When naming bugs, try to describe the use case or problem instead of the implementation unless there is no ambiguity in how the fix should be implemented. If the implementation approach helps with queries append it.

Use the Eclipse bug severity with this exception: bugs marked as Trivial are enhancements, that can be easily implemented.

Keywords

helpwanted: bugs that are beyond the current priorities for the project. Note that some bugs marked for an upcoming milestone can be marked as helpwanted. This indicates that the project committers would like to see the bug solved for the milestone and will actively contribute to a solution, but that the bug is more likely to be fixed in a timely manner with the help of additional contributors.

bugday: these are a special category of helpwanted bugs that are intended to be mast accessible or rewarding for new contributors interested in helping the project to tackle. See the Bug Day FAQ for more information. In order to keep this list focused on the most relevant bugs it is capped at 24 and should be reviewed periodically.

contributed: bugs that were resolved through a contribution from a non-committer.

plan: bugs that are part of the project plan (see below).

Tags
The project uses the following tags in the summary of bugs on bugs.eclipse.org (bug 215853):

Triage

The goal of bug triage to minimize the overhead for committers and to maintain a manageable backlog. Each (new) bug that is filed is processed as follows:

Major bugs or regressions are marked P1. If necessary the bug is escalated and scheduled for the current milestone.

Other bugs are marked P2.

Enhancements requests that should be considered for a future release are generally marked P3.

Other enhancement requests are marked P4 and tagged as helpwanted if they can be resolved through a community contribution.

If a request is out of scope of the project it is marked P5 or preferably closed. P5 bugs should not be marked helpwanted.

The backlog consists of all tasks scheduled for -- with a priority of P2 or higher. User stories are tagged with the plan keyword.

Bugs are assigned as following:

mylyn-inbox@eclipse.org: New bugs are and bugs that need user input.

mylyn-triaged@eclipse.org: Bugs that have been responded to and severity and priority has been set.

other: The owner is committed to completing the task for the scheduled milestone or within a reasonable time frame in the future if the bug is scheduled for --.

Planning

The goal of planning is to schedule a list of bugs for the milestone that concludes the next release cycle. When the milestone is reached all bugs with a priority of P3 or higher are expected to be completed. It is important that planning takes existing resources into account to avoid over-committing. Predictable release deliverables will enable integrators to plan their own progress based on the Mylyn framework and aid the growth of the ecosystem.

Before every release planning is done by triaging the entire backlog. Bugs marked with the plan keyword become part of the official release plan. Planning bugs marked P1 are committed items, other bugs are proposed items. Half way through a release cycle the plan is reviewed and P1/P2 bugs in the backlog are reconsidered for the milestone to accommodate for regressions and major bugs that were submitted after initial planning.

Resolving

The list of bugs that are scheduled for a milestone serves as a log that documents changes to release artifacts. In order to preserve historical information captured by the change log bugs that have been resolved should not be moved to other milestones once a milestone has been released.

If a defect reoccurs or a bug requires further work a new bug should be created and linked to the resolved bug. It is recommended to add a comment on the resolved bug that points to new bug and describes the reason for its creation.

Git

Git repositories can be accessed in Eclipse via EGit. Mylyn uses the following conventions for Git repositories:

It is strongly recommended to rebase before pushing to keep the revision history flat as possible:

mylyn-integration-e4.1 - Eclipse 4.1: All tests including repository tests against all supported versions

mylyn-integration-standalone - Java 1.6 : Tests designed to work outside of an OSGi environment

The full suite of repository tests is only run on the most recent Eclipse platforms. Running the full suite is expensive and a Bugzilla or Trac specific test that fails on Eclipse 3.5 is very likely to also fail on Eclipse 3.7.

Release Jobs

Release and snapshot artifacts created by release jobs are published to download.eclipse.org.

Properties

Properties control certain aspects of the build such as execution of tests or optional analysis of source code. Properties can be set by passing -D<property>=<value> to mvn. All properties are initialized to sensible default values and are optional.

tycho-version - version of Tycho to use for building

analysis.skip - set to false to run code analysis (default: true)

test.skip - set to false to run tests (default: ${maven.test.skip})

sign.skip - set to false to run code signing (default: true)

pack.skip - set to false to run pack repositories (default: false)

promote.skip - set to false to copy artifacts to download location (default: true)

TODO API x.y: This API is going to change for version x.y. Should include a description how it is going to change.

TODO e3.4: Make a change in the future specific to an Eclipse version.

XXX: The implementation uses a temporary work around that should be replaced by a proper solution in the future.

XXX SDK: The code uses internals of the Eclipse platform.

FIXME: Should only be used in very rare cases as a reminder that the marked code does not work as expected. Code marked as FIXME should not be distributed in a release.

FIXME REVIEW: Review the code before the next version is released

Creating new plug-ins and features

File a bug that describes the purpose of the new plug-ins and the proposed names. Then add an item to the weekly meeting agenda to discuss the request with other committers. Once consensus has been reached follow the steps below.

To retain consistency of layout and settings, new projects should always be created by copying an existing project rather than creating plug-in or feature projects from scratch.

Steps for creating a new plug-in or feature:

Copy an existing project on disk, e.g. to create an org.eclipse.myconnector.core bundle do the equivalent of running cp -a org.eclipse.mylyn.bugzilla.core org.eclipse.mylyn.myconnector.core

Edit pom.xml, .project and META-INF/MANIFEST to reflect the new bundle id

List the new bundle as a module in the parent pom to include it in the build

Use Import Projects from the popup menu in the Git Repositories view to add the project to the workspace

For plug-ins these additional steps should be considered:

Add bundle to feature

Add source bundle to SDK feature

For features these additional steps should be considered:

Add feature to site

Contributions

Contributions are a key part of evolving Mylyn. All committers should encourage and prioritize contributions.

Applying Patches

Note that each patch should not contain more than 250 lines of code of unique and seprately usable functionality. For larger patches we need to invoke the IP Review process.

Contributors frequently write quick patches in order to get something working for them. It is the responsibility of the committer to either encourage the contributor to improve the modularity and test coverage of the patch or to do those themselves if this aligns with the projects' priorities. Failing to do so can reduce the overall quality of the code and failing to get sufficient test coverage reduces our ability to evolve the code.

When applying a patch follow these steps:

Git

Enter the name of the contributor as the author of the commit

Encourage the contributor to update the patch into state where it can be applied unaltered.

If you need to make addtional changes that are non-trivial (e.g., copyright header fixes) commit the unaltered patch first and then make another commit with your changes.

If absolutely necessary, a task-branch can be used to group commits and improve traceability otherwise commit messages should be sufficient to associate bugs with commits.

All files altered by a contributor must have a note in the copyright header and should have an @author tag if a change was significant.

If several authors have worked on a commit consider adding Co-authored-by headers to the commit message for each author.

Web Site

Create a new CVS location: :extssh:dev.eclipse.org:/cvsroot/org.eclipse

Check out www/mylyn as a project

You need to be a member of the mylyn group to commit changes to the website.

Incubator

The Mylyn Incubator is a set of projects and feature contributors use for experimentation. These features are not intended to be used for daily development. Incubator features include experimental connectors and bridges, experimental UI features, and developer tools. To use Incubator tools either check them out of the version control, or install them using the Incubator update site.

Dev tools

Introspect Object (action): displays the class and other relevant information (e.g. degree-of-interest, task synchronization state) of any object visible in the workbench. Appears at the end of the context menu for any view that accepts an object contributions.

Experimental tools

The following experimental views can be opened via the Experimental view category or accessed via the Tasks -> Experimental preference page.

Context Search: Automatically finds and displays elements that are structurally related to landmarks in the active . These elements become part of the task context and have a predicted degree-of-interest.

Context Hierarchy: Displays the Java hierarchy of all landmark elements.

Predicted interested for Java errors: Potentially useful, but tends to overload the Package Explorer. If you find this useful for long-term use condiser commenting on bug 107542.

Tips and Tricks

User support

Every time that you find yourself formulating an answer to a bug report, email, or newsgroup post, if the answer is more than a sentence, consider updating the FAQ, User Guide, or Integrator Reference and pointing to the entry.

Every time that resolving a bug does not result in a code change that addresses the problem or clarifies the UI, update the FAQ or User Guide to make sure that users can self-diagnose the problem. This is particularly important for bugs marked INVALID or WORKSFORME.

Code

For error handling use StatusHandler and pass an IStatus object. Note that some of the other Mylyn code uses the convenience methods on StatusHandler, but we are phasing those out because they do not pass the plug-in ID that the exception originated from.

Use WorkbenchJob for running jobs that should only run when the workbench is active. Not doing this can cause errors on workbench shutdown (e.g. bug 178409).

When using String.toLowerCase(), use String.toLowerCase(Locale.ENGLISH) to ensure locale safety (see bug 168652).

Do not use @Override annotations on implementing methods, only on overriding methods. Doing so violates Java 5 (bug 173171).

Use DateFormat with extra caution. It is not thread-safe and should not be saved to fields in classes that can be used from multiple threads (UI, asynchonous execution, or jobs).

For the sake of multi-monitor setups, use getMonitor() instead of getDisplay() when you want to position a UI element on a specific coordinate of the screen.

To improve the speed of decorators use setUseHashlookup(true) on all structured viewers.

Bugzilla

Query setup: If you are added to the cc list on a report that is not picked up by your usual queries it may go unnoticed. One trick is to create a query for ALL products except the product you usually work in (and hence have queries for) and set the cc field of the query to your id. Now you will be notified of anybody adding you to the cc of a product you don't usually monitor.

JDT

Including Platform plug-ins in search: Java search (Ctrl+H > Java Search) will include all plugins in your Plugin-in Dependencies. If you want to search other plugins as well, open the Plug-ins view, right click on the desired plugin(s) and choose 'Add to Java Search'. That plugin will now always be included in your java searches.

Debugging

Task List problems: do not ask users to send or attach their Task List, since it can contain highly sensitive information. If needed ask the user to create a new workspace and try to reproduce the problem there, ensuring that they have not included any user private or company private information, and have them send that.

Plug-ins fail to load: verify that plug-in dependencies are met via the Validate Plug-in Set button on the launch configuration Plug-ins tab.

Startup failure: If you get an IStartup failure message or a ClassNotFoundException on startup this is often the result of some step in the activation of the plug-in failing.

Attempt to find the earliest exception thrown within the in the plug-in's activation process. For example, this could occur in TasksUiPlugin.start() or TasksUiPlugin.<init>.

If the cause of the failure is not straightforward, the problem could be due to a class loading race condition. This can sometimes be verified by trying a different VM like IBM's or BEA's and checking if that resolves the problem. If this is the case, please file a bug.