Skip to main content

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

Jump to: navigation, search

Difference between revisions of "Mylyn/User Guide"

m (update link to Mylyn/FAQ)
(Replaced content with "[https://github.com/eclipse-mylyn/org.eclipse.mylyn/wiki/User-Guide The user guide has a new home]")
 
(108 intermediate revisions by 19 users not shown)
Line 1: Line 1:
[[Category:Mylyn]]
+
[https://github.com/eclipse-mylyn/org.eclipse.mylyn/wiki/User-Guide The user guide has a new home]
= Introduction =
+
 
+
For '''tutorials and articles on using Mylyn''' refer to the [http://www.eclipse.org/mylyn/publications/index.php Publications page].  The role of this document is to provide up-to-date documentation on a listing of the key Mylyn features and is not intended as a tutorial, and to allow users to contribute additional documentation.
+
 
+
Mylyn is a task-focused interface for Eclipse that makes working with very large workspaces as easy as working with small ones.  Mylyn extends Eclipse with mechanisms for keeping track of the tasks that you work on. A task is defined as any unit of work that you want to recall or share with others, such as a bug reported by a user or a note to yourself about improving a feature. You can store tasks locally in your workspace, or they can come from one or more task repositories. To connect to a task repository, you must have a connector that supports that repository. (A task repository is a bug/ticket/issue tracker such as Bugzilla, Trac, or JIRA).
+
 
+
Once your tasks are integrated, Mylyn monitors your work activity on those tasks to identify information relevant to the task-at-hand.  Mylyn monitors Eclipse and captures your interaction in a task context. System artifacts such as files, types, methods, and fields get assigned a degree-of-interest based on how recently and frequently you interact with them.  This results in uninteresting elements being filtered from view within Eclipse, allowing you to focus on on what is important.  From this, Mylyn creates a task context, which is the set of all artifacts related to your task. These can include methods you have edited, APIs you have referred to, and documents you have browsed. Mylyn uses this task context to focus the Eclipse UI on interesting information, hide what's uninteresting, and automatically find what's related. Having the information you need to get your work done at your fingertips improves your productivity by reducing the time you spend searching, scrolling, and navigating. By making task context explicit, Mylyn also facilitates multitasking, planning, reusing past efforts, and sharing expertise.
+
 
+
== Tips ==
+
 
+
* If a task is stuck with outgoing changes or a mid-air collision occurrs use the Synchronize action or ''Mark -> Clear Outgoing''.
+
* The ''Task List'' can be restored via its view menu -> ''Restore Tasks from History...''
+
* If a task change set disappears or is missing items, toggle the ''Incoming/Outgoing'' mode of the ''Syncrhonize'' view.
+
* When checking out a new project, deactivate the active task. Otherwise all newly created files will become interesting.
+
 
+
== Shortcuts ==
+
<b>&nbsp;Task List view</b>
+
<ul>
+
<li><code>Ctrl+C</code>: copy taks/query URL and description</li>
+
<li><code>Ctrl+F</code>: find</li>
+
<li><code>Insert</code>: new personal task</li>
+
<li><code>F5</code>: synchronize selected</li>
+
<li>When dragging URLs to the Task List: in Mozilla/Firefox just drag, in Internet Explorer <code>Ctrl+drag</code></li>
+
</ul>
+
<b>&nbsp;General</b>
+
<ul>
+
<li><code>Alt+click</code> or <code>Alt+RightArrow</code>: show all children of an element in a focused view, then click to select. Hold down alt to keep drilling in, click on whitespace in view to show all root elements.</li>
+
<li><code>Ctrl+Shift+Alt+RightArrow</code> Quick Context View</li>
+
<li><code>Ctrl+F9</code>: activate task dialog</li>
+
<li><code>Ctrl+Shift+F9</code>: deactivate task</li>
+
<li><code>Ctrl+F12</code>: open task dialog</li>
+
<li><code>Ctrl+Shift+F12</code>: open repository task dialog</li>
+
</ul>
+
<b>&nbsp;Interest manipulation</b>
+
<ul>
+
<li><code>Ctrl+Shift+Up</code>: mark as landmark</li>
+
<li><code>Ctrl+Shift+Down</code>: mark less interesting</li>
+
</ul>
+
<b>&nbsp;Useful Eclipse shortcuts</b>
+
<ul>
+
<li><code>Alt+Shift+Q, K</code>: show ''Task List'' view</li>
+
<li><code>Ctrl+F10</code>: invoke view menu or ruler menu in editor</li>
+
</ul>
+
 
+
== UI Legend ==
+
 
+
Open the live ''UI Legend'' via ''Task List -> view menu -> Show UI Legend''
+
 
+
[[Image:mylyn-ui-legend.gif]]
+
 
+
== External Resources ==
+
 
+
Getting Started
+
* http://eclipse.org/mylyn/start
+
* http://eclipse.org/mylyn/presentations
+
* http://wiki.eclipse.org/index.php/Mylyn_FAQ
+
 
+
Instructional blog posts (feel free to add your own)
+
* [http://acer-rubrum.blogspot.com/2008/05/using-redmine-with-mylyn-eclipse-plugin.html Using Mylyn with Redmine] (2008-05-10)
+
* http://blog.vazexqi.com/articles/2008/02/02/session-restore-sort-of-in-eclipse-with-mylyn (2008-02)
+
* Using Mylyn with Google Code: http://www.jroller.com/alexRuiz/entry/using_mylyn_with_google_code (2007-08)
+
* XPlanner Connector overview: http://www.jroller.com/robwilliams/entry/first_look_xplanner_connector_for (2007-07)
+
* Filing bugs with the Bugzilla connector: http://www.peterfriese.de/index.php/2007/07/02/reporting-bugs-has-never-been-easier/ (2007-07)
+
* Overview: http://rbtech.blogspot.com/2007/05/eclipse-mylar-wow.html (2007-05)
+
 
+
= Installation =
+
 
+
Also see the [[Mylyn/FAQ#Installation_Troubleshooting | Installation FAQ]]
+
 
+
To install Mylyn, you need to
+
* [http://www.eclipse.org/downloads/ Download and install Eclipse 3.2 or 3.3]
+
* [[#Platform requirements | Ensure you meet the platform requirements]]
+
* [[#Download | Download Mylyn]]
+
After you have installed Mylyn, there are a few more configuration steps that you might wish to do:
+
* [[#Configuration|Configuration]] for workspace setup recommendations
+
* [[#Keyboard mappings on Linux|Keyboard mappings on Linux]] shows how to set up some useful key bindings.
+
* [[#Task List backup and restore|Task List backup and restore]] shows how to set up where backup files will be saved.
+
 
+
== Project Structure ==
+
 
+
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 active a task.
+
 
+
=== Main ===
+
 
+
 
+
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]. 
+
 
+
Features:
+
* '''Task List (Required)''': provides the Task List view and other task management features.
+
* '''Focused UI (Recommended)''': provides the ability to focus the Eclipse UI on the task-at-hand
+
 
+
Integration:
+
* '''Connector: Bugzilla''': trask repository integration for the Bugzilla bug tracker
+
* '''Bridge: Eclipse IDE''': focus for IDE features such as the navigator and marker views
+
* '''Bridge: Java Development''': focus for the Package Explorer and Java editor
+
* '''Bridge: Plug-in Development''': focus for PDE artifacts
+
* '''Bridge: Team Support''': automatic change set management
+
 
+
=== Extras ===
+
 
+
Mature components that are supported by community contributions.  You must add the [http://eclipse.org/mylyn/downloads Extras site] in order to install these components.
+
 
+
Integration:
+
* '''Connector: Trac''': task repository integratino for Trac
+
* '''Connector: JIRA''': task repository integration for Atlassian's JIRA issue tracker
+
 
+
=== Incubator ===
+
 
+
Incubator components vary in maturity level and are supported by the component leads. 
+
 
+
Features:
+
* '''UI Usage Reporting''': mature component for viewing Eclipse usage statistics
+
* '''UI Experiements''': user interface tweaks, not recommended for daily use
+
 
+
Integration:
+
* '''Connector: Web Templates''': mature component with templates for connecting to web-based issue trackers, advanced user interface
+
* '''Connector: XPlanner''': maturing component for connecting to the XPlanner agile project management tool
+
 
+
== Releases==
+
 
+
The best and most stable release to use is always the latest.  This goes for milestone releases (e.g. 2.0M1) which will often have bug fixes and other improvements over final release versions (e.g. 1.0.1).  The "milestone" tag only refers to the fact that the API for that release is still stabilizing. Our policy is not to destabilize, so any Mylyn build that you install should be stable, including development builds.  The UI of development builds can fluctuate.
+
 
+
'''Schedule'''
+
 
+
* Weekly builds: available every Wednesday and on-demand
+
* Release builds: see the [[Galileo]] release schedule
+
 
+
'''Weekly/Integration Builds'''
+
 
+
Integration builds are released weekly and should be used by all Mylyn contributors not self-hosting from CVS [http://wiki.eclipse.org/index.php/Mylyn_Contributor_Reference#Self-hosting straight from CVS].
+
 
+
* Eclipse '''3.5''': latest milestone release is fully supported (e.g., 3.4M1)
+
* Eclipse '''3.4''': latest release is fully supported (e.g., 3.4.1)
+
* Eclipse '''3.3''': latest release is fully supported (e.g., 3.3.2)
+
* Eclipse '''3.2''': not suported, use Mylyn 2.0.0 (reached end-of-life)
+
 
+
'''Task List and Context Store Compatibility'''
+
 
+
The Task List and Context Store are compatible across all currently-supported Eclipse versions.  This means that you can use the same .mylyn data in both Eclipse 3.2 and 3.3.  For Mylyn versions that have reached their end-of-life we specify the update path so that the contents of the .mylyn folder are updated.  This is listed in the "Update notes" on top of the [http://eclipse.org/mylyn/new New & Noteworthy].
+
 
+
'''Task context compatibility'''
+
 
+
Task contexts can be shared with any previous released version of Mylyn.  Note that if elements have been renamed they may not appear as interesting when the context is activated.
+
 
+
== Download ==
+
 
+
For supported platforms and known limitations please see the [http://eclipse.org/mylyn/dl.php Mylyn download page].
+
 
+
The recommended way to install Mylyn is from inside Eclipse:
+
# Select ''Help->Software Updates->Find and Install''.
+
# Select ''Search for new features to install'' and select ''Next''.
+
# Select ''New Remote Site''.
+
# Enter "Mylyn" for the name and insert the download site given on the [http://www.eclipse.org/mylyn/dl.php Mylyn downloads page].  The URL should end up as something similar to <code>http://download.eclipse.org/tools/mylyn/update/eX.Y.</code> where X.Y is the Eclipse release number.
+
## Eclipse 3.2: <code>http://download.eclipse.org/tools/mylyn/update/e3.2</code>
+
## Eclipse 3.3: <code>http://download.eclipse.org/tools/mylyn/update/e3.3</code>
+
## Eclipse 3.4: <code>http://download.eclipse.org/tools/mylyn/update/e3.4</code> (probably)
+
# Select ''OK''.
+
# Make sure there is a check in the ''Mylyn'' box, and select ''Finish''.
+
# Put a check in the box next to ''Mylyn''.  If you don't mind downloading some stuff you don't need, go ahead and select ''Next''.  Otherwise, expand the ''Mylyn'' line (by clicking on the disclosure triangle) and select what you want.  We recommend downloading the ''Task List'', the ''Focused UI'', and connectors appropriate to the bug repository that you use -- Bugzilla, Trac, or Jira.  (Note that to download Jira, you need both the core and the connector.)  You can download Mylyn without a bug repository, but it won't be as interesting an experience. If you download the Focused UI you will want to also choose the Bridge appropraite to the content you work with. Most developers will want to include all bridges provided.
+
# Read the license agreements, accept or decline as appropriate, and either select ''Next'' (if you accept) or ''Cancel'' (if you do not accept). 
+
# You will see a list of features and where to install them.  If the default installation directory is fine, select ''Finish''.
+
+
'''Optional Extras'''
+
There are optional Mylyn extras available at a separate update site: http://download.eclipse.org/tools/mylyn/update/extras. This update site includes projects still in incubation. As of writing this update site includes the JIRA Connector, the Generic Issue Tracker Connector, and UI Usage Reporting facility.
+
 
+
'''Errors you might get during the download process:'''
+
 
+
*'''Network connection problems encountered during search''' means that Eclipse couldn't find the location you entered.  This might be because you copied something incorrectly (watch for extra characters -- even extra spaces can cause errors), or because the site went down.  You might be able to see if the site is down by copying the URL into your Web browser.
+
 
+
*'''Update manager failure''' means that Eclipse could not access the update site, or that it got confused about the configuration state of your Eclipse.  First try updating again to see if the update site is accessible. 
+
 
+
*If you are trying to update the JIRA connector you can also try de-selecting that feature in case the Tigris.org update site is not accessible.  Using use ''Search for new features..'' when installing can help to avoid this problem.  If that does not work see the [[#Configuration| feature configuration troubleshooting]] below.
+
 
+
*You will probably get a warning that '''the feature is unsigned'''.  If you trust that hackers have not befouled the Mylyn plug-in, select ''Install All''.
+
 
+
*You will get a dialog box asking if you would like to restart Eclipse.  We recommend that you select ''Yes''.  <!-- If you are running Eclipse from the command line, it might be worthwhile to start it once with  (@@@? true?) eclipse -clean -->
+
 
+
== Platform requirements==
+
 
+
Mylyn requires the '''Java 5''' virtual machine.  To check the version of the Java virtual machine that Eclipse was launched with to to ''Help -> About Eclipse SDK -> Configuration Details'' and verify that the java.vm.version is 1.5. 
+
 
+
Mac users should refer to the last comment on [https://bugs.eclipse.org/bugs/show_bug.cgi?id=116347#c4 bug 1163477] for instructions on how to change the 1.4 default.
+
 
+
* If you do not have Java 5, you can download it from [http://java.sun.com/javase/downloads/index.jsp Sun's web site].
+
* If you have more than one VM, you need to specify that Eclipse should use the JDK1.5 VM. 
+
 
+
<b>We do [https://bugs.eclipse.org/bugs/show_bug.cgi?id=140955 not recommend] using JDK 1.6 on Eclipse 3.1.</b> (It works fine with Eclipse 3.2 or 3.3.) To use JDK 1.6 on Eclipse 3.1, you must add the following line to your config.ini file:
+
 
+
    org.osgi.framework.executionenvironment=OSGi/Minimum-1.0,OSGi/Minimum-1.1,JRE-1.1,J2SE-1.2,
+
    J2SE-1.3,J2SE-1.4,J2SE-1.5,JavaSE-1.6
+
 
+
<b> Linux and JVM issues</b>
+
 
+
For those experiencing unstable performance with Linux using the Sun JVM, download the [http://www-128.ibm.com/developerworks/java/jdk/linux/download.html IBM JVM], which will require you to register with IBM prior to download.
+
 
+
 
+
'''In Unix''', set the environment variable <code>JAVA_HOME</code> to the root of the JDK1.5 installation and/or set the <code>PATH</code> variable to put the JDK1.5 executable directory before any other VM executable directories.  For example, under <code>bash</code> in Unix:
+
 
+
export JAVA_HOME="''(location of JDK1.5 root)''"
+
export PATH=$JAVA_HOME/bin:$PATH
+
 
+
== Installing on Linux ==
+
 
+
=== Browser issues ===
+
 
+
Mylyn uses the Standard Widget Toolkit Browser, and users have experienced problems with the SWT Browser on Linux.  This is not a Mylyn specific problem and also occurrs if you try to use Eclipse's Browser view.  There are two options:
+
* Follow the instructions below to get the browser properly configured
+
* Disable the ''Browser'' tab showing up on tasks via ''Preferences -> Mylyn -> Task List''
+
 
+
When the Browser is not properly configured exceptions such such as "Could not create Browser page: No more handles (<code>java.lang.UnsatisfiedLinkError: ...</code>)" will appear when attempting to open tasks.  See [http://www.eclipse.org/swt/faq.php#browserlinux the SWT Browser guide] for which browsers will work. 
+
 
+
[http://www.mozilla.org/projects/seamonkey/ Seamonkey] is reported to work well. Just install and then point MOZILLA_FIVE_HOME to /usr/lib/seamonkey. (read below for example of setting this variable)
+
 
+
To test to see if your browser is properly configured, select ''Window -> Show View -> Other -> General -> Internal Web Browser'', then try to bring up a web page.
+
 
+
 
+
* A quick work-around is to disable the internal browser pages in Mylyn editors. To do this: ''Window -> Preferences -> Mylyn -> Tasks -> Disable Internal Browser''.
+
*Before testing the browser support in Mylyn, you must first ensure that the Eclipse internal browser is correctly configured. To test to see if your browser is properly configured, select ''Window -> Show View -> Other -> General -> Internal Web Browser'', then try to bring up a web page.
+
*'''Notice''': You must use the GTK2 version of Mozilla for internal browser integration.
+
*'''Notice''': The internal browser does not correctly support HTTPS.  See [https://bugs.eclipse.org/bugs/show_bug.cgi?id=80033 bug 80033].
+
 
+
 
+
Mylyn Task Management features makes use of Eclipse's internal browser, which may require additional install steps listed below.  You also have the option of disabling Mylyn's use of the internal browser via ''Preferences -> Mylyn -> Tasks''.
+
 
+
The following steps have been verified on Fedora Core 5, and OpenSuSE 10.1.
+
# Run Mozilla '''(not Firefox)''' to confirm that it works.
+
# Confirm the location of your Mozilla install (ex: <code>/usr/lib/mozilla-1.7.12</code>)
+
# Set necessary environment variables in <code><home_directory>/.bashrc</code>, adding the following 3 lines
+
 
+
    MOZILLA_FIVE_HOME=/usr/lib/mozilla-1.7.12
+
    LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$MOZILLA_FIVE_HOME
+
    export MOZILLA_FIVE_HOME LD_LIBRARY_PATH
+
 
+
For Debian Etch and newer use the following MOZILLA_FIVE_HOME:
+
 
+
    MOZILLA_FIVE_HOME=/usr/lib/iceape
+
 
+
:4. Log out and log in again (or type "<code>source .bashrc</code>" at the prompt)
+
:5. Start Eclipse and test the internal web browser
+
 
+
If you are getting exceptions indicating missing libraries, check that the paths are accurate and that you have the libraries required. For example, on our test box a library was still missing after these steps. The <code>libstdc++.so.5</code> was being reported as missing. To solve this problem, find an <code>rpm</code> online that will install the missing legacy library. In our case we found necessary <code>rpm</code> (<code>compat-libstdc++-33-3.2.3-47.fc4.i386.rpm</code>) on [http://rpmfind.net/ rpmfind.net] using their search facility.  See also: [http://www.eclipse.org/swt/faq.php Standard Widget Toolkit FAQ]
+
 
+
'''Memory consumption problem with internal browser on Linux-GTK'''
+
 
+
If you are experiencing abnormal memory consumption upon launching the internal browser (or opening repository tasks), try shutting down eclipse, renaming/moving your <code>~/.mozilla/eclipse</code> folder and relaunching eclipse. (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=173782 bug#172782])
+
 
+
=== Recommended GTK Setup for KDE ===
+
 
+
The recommended GTK theme to use for KDE (and KDE based distributions like Kubuntu) is the
+
"Human" theme. (Possibly, this is also a good recommendation for GNOME. GNOME users, please comment.)
+
 
+
With Debian based distributions (e.g. Ubuntu), this theme can be installed with
+
 
+
  aptitude install human-theme
+
 
+
The appearance of GTK applications is controlled by the KDE System Settings / Control Center
+
in the section "Appearance".
+
 
+
;GTK Styles and Fonts: GTK Styles: Select "Use another style [Human]"
+
 
+
;Colors: At bottom: [x] Apply colors to non-KDE applications
+
 
+
These changes are applied to these two GTK configuration files, respectively:
+
 
+
* <tt>$HOME/.gtkrc-2.0-kde</tt>
+
* <tt>$HOME/.kde/share/config/gtkrc-2.0</tt>
+
 
+
'''Solving issues with KDE environment variable settings'''
+
 
+
Most of the [[#Known_UI_issues_with_KDE | known UI issues below]] are due to a broken environment variable setting. The environment variable <tt>GTK2_RC_FILES</tt> contains a search path to find the GTK configuration files to be used by the GTK application and can be checked with
+
 
+
  env | grep GTK2_RC_FILES
+
 
+
The correct setting is obtained by
+
 
+
  export GTK2_RC_FILES=$HOME/.gtkrc-2.0-kde:$HOME/.kde/share/config/gtkrc-2.0 ''# Bourne shell''
+
  setenv GTK2_RC_FILES $HOME/.gtkrc-2.0-kde:$HOME/.kde/share/config/gtkrc-2.0 ''# C shell''
+
 
+
'''Important note:''' The used environment setting seems to differ depending on the way KDE starts
+
the application: from Konsole, using "Run Command...", using a desktop icon etc. Please use this simple script to check the different ways:
+
 
+
  #!/bin/bash
+
  env | grep GTK2_RC_FILES >/tmp/GTK2_RC_FILES.env
+
 
+
and look at the resulting output in <tt>/tmp</tt>.
+
 
+
Consider filing a bug against the distribution showing this inconsistent behaviour.
+
 
+
'''Known UI issues with KDE'''
+
 
+
There a couple of bugs related to UI features not working in specific Linux distributions:
+
 
+
* [https://bugs.eclipse.org/bugs/show_bug.cgi?id=176716 176716: Task colors are not displayed]
+
* [https://bugs.eclipse.org/bugs/show_bug.cgi?id=173928 173928: Task acivate button does not work under linux]
+
 
+
Debian 3.1 (sarge) with KDE and standard X11 installation (XFree86) works fine for all three issues.
+
 
+
Debian testing (etch) with KDE and new X11 installation (X.Org) has issues with the color display (bug 176716 and 135928), but the Task Activate button works.
+
 
+
Kubuntu Dapper 6.06 with KDE and X.Org triggers all above issues. An upgrade to Edgy enables Task Color display and the date picker selection. To get the Task Activation button working you have to use Edgy and Eclipse 3.3M5eh (or newer).
+
 
+
Kubuntu Gutsy 7.10 has issues with the color display (bug 176716). A workaround is to change the GTK-Style to "Human".
+
More details and another solution in the comments of bug 176716.
+
 
+
== Installing on MacOS ==
+
 
+
If you see errors like the following it may be due to Xerces missing from the Mac JDK so you may need to add it to your default classpath.  Please refer to and comment on [https://bugs.eclipse.org/bugs/show_bug.cgi?id=144287 bug 144287] if you see this problem.
+
 
+
    Could not create Bugzilla editor input
+
    java.io.IOException: SAX2 driver class org.apache.xerces.parsers.SAXParser not found
+
 
+
To ensure that you are using the 1.5 VM refer to the last comment on [https://bugs.eclipse.org/bugs/show_bug.cgi?id=116347#c4 bug 1163477] for instructions on how to change the 1.4 default.
+
 
+
== Rich Task List Install ==
+
 
+
Mylyn's Task Management features can be used purely as a rich client to supported bug/task/issue trackers, and do not require the programming facilities of the full Eclipse SDK.
+
 
+
For example, to use Mylyn as a rich client for Bugzilla:
+
* Install the [http://download.eclipse.org/eclipse/downloads/drops/R-3.2-200606291905/index.php Eclipse 3.2 Platform Runtime] binary (e.g. for [http://download.eclipse.org/eclipse/downloads/drops/R-3.2-200606291905/download.php?dropFile=eclipse-platform-3.2-win32.zip  Windows], [http://download.eclipse.org/eclipse/downloads/drops/R-3.2-200606291905/download.php?dropFile=eclipse-platform-3.2-linux-gtk.tar.gz Linux x86/GTK 2], [http://download.eclipse.org/eclipse/downloads/drops/R-3.2-200606291905/download.php?dropFile=eclipse-platform-3.2-macosx-carbon.tar.gz Mac OSX]).
+
* Use the update site listed on [http://www.eclipse.org/mylyn/dl.php Mylyn download page] for installing the Task List and Bugzilla Connector.  Note that Mylyn requires Java 5.
+
 
+
== Starting Mylyn for the first time ==
+
Once everything has been installed, upon restarting, you will see a dialog box titled ''Mylyn Recommended Preferences''.  It's probably best to accept the defaults unless you are already familiar with Mylyn. 
+
 
+
Mylyn introduces a number of views to the Eclipse workbench that can be found via Window->Show View->Other, under the ''Mylyn'' category.
+
 
+
= Configuration =
+
After you have installed Mylyn, there are a number of things that you can configure to make your experience even richer.
+
 
+
== Eclipse settings ==
+
Recommendations for workspace configuration when using Mylyn:
+
* '''Package Explorer'''
+
** Use flat layout in the Package Explorer (local pull down -> ''Layout -> Flat'' or ''Package Presentation -> Flat'').
+
** Leave the ''General -> Appearance -> Label Decorations -> Java Type Indicator'' off.  The type is visible under the Java file when Mylyn is applied making such additional information redundant.
+
* '''Editors'''
+
** Turn comment folding on to reduce clutter when using auto folding (''Preferences -> Java -> Editor -> Folding'').
+
* '''Views'''
+
** Outline: can keep closed for Java development, since the Package Explorer and folded signatures should provide enough context, and the in-place Outline <code>Ctrl+O</code> can be used when needed.
+
* '''Team'''
+
** Set ''Synchronize'' view to ''Change Sets'' mode (on 3.2: third toolbar button: select ''Change Sets'';  on 3.1: toggle toolbar button: ''Show Change Sets'')
+
** Use graphical CVS decorators only (''Preferences -> Team -> CVS -> Label Decorations -> Text Decorations'' -> clear all but ''Project''; ''Icon Decorations'' -> enable all).  This helps reduce visual clutter.
+
 
+
== Query setup ==
+
 
+
While there are many ways to set up queries (e.g. by component, by milestone) we recommend the following as a starting point.  For each repository, create:
+
 
+
# One query for all tasks assigned to you.  This should include all closed/resolved tasks in order to prevent resolved tasks from dropping into the "Archive" container.  There is no performance problem with having thousands of resolved tasks in your Task List.
+
# All tasks assigned to each person that you work with closely.  This can include peers or people you manage and makes it easier to collaborate.
+
# All tasks that you are CC'd on.  To this you can additionally add tasks that you have commented on and created/reported.  This will prevent you from needing to rely on email notifications, since it captures all tasks of interest.  For example, with this this configruation you can turn off Bugzilla email notifications or have them automatically categorized/filed out of yor email inbox. 
+
 
+
Depending on how you set up (1) and (2), you may want to limit (3) to certain components in order to avoid tasks showing up in multiple containers.
+
 
+
== Workspace setup ==
+
 
+
The following is an example of how to set up your Eclipse to work with a single workspace in a way where you can use Mylyn to focus you on your task while using ''Working Sets'' to maintain only a single workspace while keeping project/product boundaries clear.
+
* Create a ''Working Set'' for each project/product that you have checked out.
+
** NOTE: we recommend not overlapping your working sets, e.g. having ProjectFoo in both WorkingSetA and WorkingSetB.  Doing so will cause the project to show twice when the Focus filter is on.
+
* Set the ''Package Explorer'' to show ''Working Sets'' as the top-level elements.
+
* Set the ''Problems'' view to filter out warnings from any ''Working Sets'' that you do not contribute to.
+
* Set the ''File Search'' scope to only include ''Working Sets'' that you contribute to.
+
 
+
When using working sets, the second drop down arrow (Task Activation History) will reveal task activation history for the currenlty selected working set. Choosing a different working set will then only reveal tasks previously activated while the that working set was active. To see the aggregate of all previously active tasks in the task activation history drop down you need to select "Show All" from the work set selection drop down.
+
 
+
 
+
== UI Settings ==
+
 
+
This section is evolving, please consider adding your own UI settings.
+
 
+
* Landmark background color: ''Window -> Preferences -> General -> Editors -> Text Editors -> Annotations'', then select ''Landmark'' and use the ''Color'' chooser.
+
* Text colors and fonts: ''Window -> Preferences -> General -> Appearance -> Colors and Fonts'', then select the corresponding category and kind.
+
 
+
== Spell checking ==
+
 
+
On Eclipse versions earlier than 3.3, the spell checking must be set up manually.  Spell checking is supported in the task editor for local tasks and for connectors that support rich editing (e.g. Bugzilla, Trac).
+
* To install spell checking for editors that support it you need to enable the preference in ''General -> Editors -> Text Editors -> Spelling''.
+
* You also need to install a dictionary, some instructions are [http://www.javalobby.org/java/forums/t17453.html here]. A word list is available [[http://wordlist.sourceforge.net/ here]] as well.
+
 
+
[[Image:mylar-spell-checking-preference.gif]]
+
 
+
 
+
== Key Mappings ==
+
 
+
If default key mappings aren't working, try doing the following to reset them:
+
* ''Window -> Reset Perspective''
+
* ''Then: Window -> Preferences -> Keys -> Restore Defaults''
+
 
+
'''Linux'''
+
 
+
If you are running Mylyn on X-Windows, for example on Linux, FreeBSD, AIX and HP-UX, some keyboard bindings may not work by default.
+
 
+
If the <code>Ctrl+Alt+Shift+Arrow Up</code> shortcut for ''Mark as Landmark'' does not work do the following:
+
* ''Menu Bar -> Desktop -> Control Centre -> Keyboard Shortcuts -> Move one workspace up, Move one workspace down'': disable both.
+
 
+
If <code>Alt+Click</code> quick unfiltering does not work try one of the following:
+
* Hold down the <code>Windows</code> key while holding <code>Alt</code>, if available (ironic, but unsurprisingly this key is not usually mapped on Linux).
+
* Disable the <code>Alt+drag to move</code> functionality:
+
GNOME Desktop
+
# Open a terminal and run <code>gconf-editor</code>
+
# Go into: <code>/apps/metacity/general</code>
+
# Edit the <code>mouse_button_modifier</code> field. Setting it to nothing disables it. You can use <Super> to set it to the windows key.
+
# Exit <code>gconf-editor</code>.
+
KDE Desktop
+
# Run the ''KDE Control Center''.
+
# Go to the ''Desktop/Window Behavior'' panel and select the ''Window Actions'' tab.
+
# Down in the ''Inner Window, Titlebar & Frame'' area, change the ''Modifier Key'' option from <code>Alt</code> to <code>Meta</code>.
+
 
+
Reconfiguring Eclipse to use the <code>Meta</code> or <code>Win</code> key instead is not possible due to the Eclipse bug
+
[https://bugs.eclipse.org/bugs/show_bug.cgi?id=55236 55236: Please support SWT.MOD4 on platforms other than the Mac]. Consider voting on that bug if you feel that should be possible.
+
 
+
Also, see [[Mylyn_Tips_and_Tricks#Keyboard_Shortcuts| keyboard shortcuts]].
+
 
+
== System Properties ==
+
 
+
The system properties below can used to change the behavior of Mylyn. To set a property pass it on the command line when starting Eclipse:
+
<code>eclipse -vmargs -Dorg.eclipse.mylyn.property=value</code>.
+
 
+
{|
+
|System Property || Mylyn Version || Default || Description
+
|-
+
|<code>org.eclipse.mylyn.activateTask</code>
+
|3.1
+
|<code>true</code>
+
|<code>false</code> Disable task activation on startup.
+
|-
+
|<code>org.eclipse.mylyn.linkProviderTimeout</code>
+
|3.1
+
|5000
+
|Number of milli-seconds before link providers are timed out. Set to -1 to disable link providers timing out.
+
|}
+
 
+
= Task List =
+
 
+
== Icon Legend ==
+
 
+
Please see the [http://www.eclipse.org/mylyn/tips Tips & Tricks page].
+
 
+
Open the UI Legend via the Task List view menu button located next to minimize button in top right corner of Task List view)
+
 
+
== Task Creation ==
+
 
+
There are several ways to create new tasks:
+
* ''Task List'' toolbar item
+
* ''Task List'' context menu, which contains a new ''Local Task'' action that will create local tasks without briging up repository selection.  Shortcut is the Ins key, if available.
+
* ''File -> New'' or Alt+Shift+N, T (note that you may need to reset your perspective to have ''Task'' and ''Query'' automatically appear in the Alt+Shift+N menu).
+
 
+
== Incoming Changes ==
+
 
+
A blue arrow indicates that a task has changed in the repository. To quickly review the differences since the task was last read hover over the task or press F4 to display a tooltip.
+
 
+
To filter the task list to incoming changes and tasks scheduled for this week use the Focus on Workweek button in the toolbar. Another way to quickly find tasks with incoming changes is to use Alt+down in the Task List which jumps to the next task with an incoming change.
+
 
+
In addition the UI Experiments feature that is part of the Mylyn incubator contributes a task list presentation that only shows tasks with incoming changes.
+
 
+
== Scheduling ==
+
 
+
Mylyn provides two kinds of dates for scheduling.
+
 
+
''Scheduled Date''
+
* A soft date intended for personal scheduling and can be easily deferred as priorities change.  Intended to be the date that you plan to start working on the task.
+
* Once a task hits its start date it will turn red, indicating that the task should be activated and worked on.
+
* If you schedule a task for ''Today'' it will turn blue instead of red and be scheduled for the end of your workday, as specified in ''Preferences -> Task List''.  This is to help avoid needing to reschedule tasks throughout the workday.  At the end of the workday tasks will turn red.
+
* When you schedule a task for "today" it will be scheduled for the
+
 
+
''Due Date''
+
* A hard date he date that the task has to be completed by.  This is hard date and often related to external constraints such as deadlines.
+
* If shared task repositories or calendaring tools are used due dates are synchronized in order to be visible to other team members.
+
* A task with a due date has a small clock overlay that is blue before the date and red after.
+
 
+
== Weekly Progress ==
+
 
+
When in ''Focus on Workweek'' mode (right-most toolbar button), the Task List will show a JUnit-style progress bar which indicates progress on the tasks scheduled for that week.  Each task that is scheduled for the week but not yet completed adds to the bar.  A task completed by you adds to the green progress in the bar.  Deferring a task to a future week will also add to the apparent progress because it will remove the task from the current week.  Mousing over the bar will indicate details about your progress, such as the number of tasks and hours completed.  To avoid the need for manual estimation by default every task is estimated for 1 hour, but if you have longer or shorter running tasks that week you can adjust the estimate in the task editor's ''Planning'' page to ensure that the progress bar is accurate. 
+
 
+
Note that when in ''Focus on Workweek'' mode the ''Task List'' will show each of the tasks scheduled for this week.  However, overdue tasks and those with incoming changes will also show, making the number of tasks visible not be a reliable indicator of progress on the tasks planned for the week.
+
 
+
[[Image:Weekly-progress.gif]]
+
 
+
== Progress for Categories ==
+
 
+
Categories show progress for the number of completed tasks. 
+
 
+
[[Image:Progress-categories.gif]]
+
 
+
== Incoming Changes ==
+
 
+
All comments added since your last reading of a repository task will be automatically expanded when a task with incoming changes is opened.  Incoming changes are retrieved with the background synchronization to avoid waiting for the server when opening.  Note that a background synchronization is still kicked off upon opening in case changes came in since the last scheduled synchronization.  Repository tasks can be explicitly marked as read or unread.
+
 
+
[[Image:Incoming-changes.gif]]
+
 
+
== Task Repository Integration ==
+
 
+
Task repositories are easy to add, and can be named via the ''Task Repositories'' view.  An icon decoration indicates the repository type.  A task repository can be associated with a project, enabling it to be used for actions such as resolving bug hyperlinks.  '''Note:''' you do not need to associate all of your projects with repositories after updating, since you will be prompted to do this when the associate is needed.
+
 
+
[[Image:Task-repository-integration.gif]]
+
 
+
After the Task Repository has been setup and associated with a project, you need to create a new query against that repository to pull down the task list.
+
 
+
See [http://www.ibm.com/developerworks/java/library/j-mylyn1/#repositories Task-focused programming with Mylyn, Part 1], Querying a repository.
+
 
+
== Open Task dialog ==
+
 
+
An ''Open Type'' style dialog is available for opening tasks (<code>Ctrl+F12</code>) and for activating tasks (<code>Ctrl+F9</code>).  The list is initially populated by recently active tasks.  The active task can also be deactivated via <code>Ctrl+Shift+F9</code>.  This can be used as a keyboard-only alternative for multi-tasking without the ''Task List'' view visible.  These actions appear in the ''Navigate'' menu.
+
 
+
[[Image:Open-task-dialog.gif]]
+
 
+
== Open Repository Task dialog ==
+
 
+
For tasks not available on ''Task List'' view, there is a ''Open Repository Task'' dialog (<code>Ctrl+Shift+F12</code>). On this case, the task can be opened by informing its ID and repository. This way the task will be retrieved from repository without being added to task list.
+
 
+
Optionally, you can add the remote task to task list, by checking the ''Add to Task List category'' option and informing the category where it will be inserted.
+
 
+
Multiple tasks can be added simultaneously by informing a sequence of IDs, separated by commas, e.g. "1,2,3".
+
 
+
== Repository task attachments ==
+
 
+
Repository task attachments (supported by the Bugzilla and Trac connectors) can be attached via drag-and-drop from both within the Eclipse workspace and from outside, and from text selections, which will invoke the attachment wizard. Attachments can be opened with a browser or corresponding editor.
+
 
+
[[Image:Repository-task-attachments.gif]]
+
 
+
== Hyperlinking ==
+
In the task editor, comments that include text of the form bug#123 or task#123 or bug 123 will be hyperlinked. In order to support hyperlinks within other text editors such as code or txt files, the project that contains the file must be associated with a particular task repository. To do this, right click on the project > Properties > Task Repository and select the task repository used when working with this project. Then in the editors such as the java source editor or the default text editor, enter a reference such as bug#123. Ctrl+clicking on this text will open the bug in the rich editor.
+
 
+
== Task List backup and restore ==
+
 
+
'''Where does Mylyn keep the task list?'''
+
 
+
By default Mylyn keeps your task list in <workspace>/.mylyn/tasklist.xml.zip.  You can change this in the Mylyn Task List preferences (''Window -> Preferences -> Mylyn -> Task List -> Task Data'').
+
 
+
'''Where does Mylyn keep the task list backups?'''
+
 
+
By default, Mylyn keeps the task list backups in the <code><workspace>/.mylyn/backup</code> folder.
+
The location of this file, as well as backup scheduling, can be changed in ''Preferences -> Mylyn -> Tasks'' in the ''Task Data -> Backup'' section.
+
 
+
'''How do I restore my task list from a backup?'''
+
 
+
Task and context data can be restored from a backup snapshot zip file via  ''File -> Import -> Mylyn Task Data''.  By default backup snapshots are taken daily and kept for 30 days.
+
 
+
[[Image:Tasklist-restore.gif]]
+
 
+
'''Can I create manual backups?'''
+
 
+
Yes. Use ''File -> Import/Export ->  Mylyn Task Data''. 
+
 
+
[[Image:mylar-tasklist-backup.gif]]
+
 
+
'''Note:'''  uninstalling a connector will cause all of the queries and tasks of that kind to disappear from the Task List, but if you reinstall that connector they will reappear.
+
 
+
'''If the Task List is blank''', either Mylyn failed to install or update, or there was a problem reading the Task List.  By default Mylyn keeps your Task List in <code><workspace>/.mylyn/tasklist.xml</code>.  If you move workspaces, and have not changed the Mylyn data directory via the ''Task List'' preference page, the new location will be used when Eclipse restarts (hit ''Restore Defaults'' on that page to copy tasks back to the default location).  If your tasks disappear due to to a bug you can check the <code>.mylyn</code> folder for a <code>tasklist-backup.xml</code> file, which will contain the previously-saved list.
+
 
+
== Report Bugs from Error Log ==
+
 
+
Bugs can created directly from events in the ''Error Log'' view.  This will create a new repository task editor with the summary and description populated with the error event's details.  If the Connector you are using does not have a rich editor, the event details will be placed into the clipboard so that you can paste them into the web-based editor that will be opened automatically.
+
 
+
[[Image:Report-bugs-error-log.gif]]
+
 
+
== Automatic Duplicate Detection ==
+
 
+
The ''Search for Duplicates'' button on the ''New Repository Task'' editor encourages and facilitates finding similar bug reports before creating a new one.  Potential duplicates are displayed in the Search view which can be used to open a bug and comment or vote if a duplicate is found.  The current duplicate detection mechanism uses stack traces, either automatically inserted by the ''Report as Bug'' mechanism, or manually pasted into the ''Description'' area.  All descriptions and comments of bugs on the corresponding repository are included in the search.
+
 
+
[[Image:Automatic-duplicate-detection.gif]]
+
 
+
== Submitting Contexts ==
+
 
+
When submitting comments, contexts can be attached by selecting the corresponding check-box in the ''Actions'' section.
+
 
+
[[Image:Submitting-contexts.gif]]
+
 
+
== Keybindings ==
+
 
+
{|
+
| F2 || rename
+
|-
+
| F4 || show tooltip
+
|-
+
| F5 || synchronize
+
|-
+
| Alt + Down || go to next unread
+
|-
+
| Alt + Up || go to previous unread
+
|-
+
| Alt + Shift + R || mark as read
+
|-
+
| Alt + Shift + U || mark as unread
+
|-
+
| Esc || hide tooltip
+
|-
+
| Enter || open task
+
|-
+
| Insert || new local task
+
|-
+
| Ctrl+C || Copy details
+
|-
+
| Ctrl+F || Find
+
|}
+
 
+
= Task Repositories =
+
 
+
== Opening a Repository Task ==
+
 
+
The recommended way to access repository tasks is with ''Queries''.  For example, you can add a query for every task assigned to you and every task that you are CC'd on.  However, sometimes you may know a particular task key or ID, and want to access it without creating or modifying a query. 
+
 
+
The quickest way to do this is to enter the task's key into the ''Find'' box in the ''Task List''.  You will immediately see whether this task is already in your ''Task List''.  If not, click the ''Search repository for key or or summary, and then simply hit <code>Enter</code> once the Search dialog comes up. 
+
 
+
[[Image:MylynSearchById.png]]
+
 
+
The <code>Ctrl+Shift+F12</code> shortcut can also be used to invoke this action, and will additionally inspect the contents of the clipboard to look for a task key/ID to populate the Task Search dialog with (e.g., if you copied they key from an email message).  The <code>Ctrl+F12</code> Open Task dialog also provides a link to the Task Search page.  Note that off a task is selected in the active editor or the Task List, the repository in the Search dialog will be now automatically set to the corresponding repository, otherwise the previous repository will be used.
+
 
+
There other common ways of getting a particular repository task into your Task List are:
+
 
+
* Drag the URL of the task into the ''Task List''.  Note that you need to hold down <code>Ctrl</code> if dragging from Internet Explorer.
+
 
+
* Search for the task and use the popup menu in the ''Search'' view or on the task editor after opening.  Note that you can also create a ''Task List'' query from a search via the ''Search'' view.
+
 
+
== Synchronization ==
+
 
+
Repository tasks and queries are synchronized in order to reflect the latest changes.  These changes are decorated with an incoming arrow, shown in the tooltip for the task, and highlighted in the task editor when opened.  All tasks changed on the server are synchronized, not just those that match queries.  Note that Mylyn does not have an explicit offline mode and does not require that you turn off synchronization when working offline.
+
 
+
Tasks are synchronized the following ways:
+
 
+
* Automatically: by default tasks will be incrementally synchronized with the repository every 20 minutes.  Automatic synchronization can be disabled via the ''Synchronize Automatically'' option in the view menu (e.g. when working with intermittently available connectivity).  The synchronization interval can be changed via ''Preferences -> Mylyn -> Task List''. 
+
 
+
* On open: tasks are synchronized automatically in the background when a task editor is opened.
+
 
+
* Manually: tasks can be synchronized manually via the Synchronize actions on ''Task List'' elements or via the toolbar.
+
 
+
''Disconnected mode''
+
 
+
A task repository can be put into Disconnected mode via the popup menu in the ''Task Repositories'' view.  This can be useful if the task repository is not being used any more (e.g. no longer engaged with the project), or is no longer available (e.g. no longer available online).  Mylyn's offline support will ensure that you can still access tasks that you have worked with via their offline copies, and the Disconnected mode will ensure that synchronization warnings do not appear.
+
 
+
=== Synchronizing All Tasks ===
+
 
+
If properties of a repository change that are not picked up by automatic synchronization, e.g. the user get assigned additional privileges in the repository, it can be desirable to do a manual synchronization. Since Mylyn 2.2 the popup menu in the ''Task Repositories'' view has an entry ''Synchronize All Tasks'' to refresh cached information for all tasks in the task list for that repository.
+
 
+
= Task-Focused UI =
+
 
+
== Alt+Click navigation ==
+
 
+
When a view is in Focused mode, you can Alt+Click a node in order to temporarily show all of it's children. 
+
* Once an element that was not interesting is selected with the mouse, the uninteresting elements will disappear.
+
* Alt+Right Arrow can be used instead of Alt+Click, but still requires a mouse selection of an element in order for the uninteresting elements to disappear.
+
* Alt+Click can be held down when drilling down from a top-level element, e.g. navigating from a project element with everything filtered right down to a method declaration.
+
* Multiple Alt+Clicks are supported, but as soon as a normal click is made uninteresting elements will disappear.
+
* Ctrl+clicks (i.e. disjoint selections, use Command key on Mac) are also supported and will cause each element clicked to become interesting.  The first non Ctrl+click will cause uninteresting elements to disappear.  Note that Ctrl+clicked element will become interesting (turn from gray to black) but only the most recently-clicked one will be selected while Alt is held down.
+
 
+
== Automatically toggle focus on navigator views ==
+
 
+
For navigator views (''Package Explorer'', ''Project Explorer'' and ''Navigator'') the ''Apply Mylyn'' button can be set to automatically toggle on with task activation and off with task deactivation.  Note that the context-related preferences (including this one) are in ''Preferences -> Mylyn -> Context.''
+
 
+
[[Image:Auto-appy-mylar.gif]]
+
 
+
== Working Set integration ==
+
 
+
When Focus is applied to a navigator view the working sets filter for that navigator view will be disabled, ensuring that you see elements when working on elements that span working sets.  In order to force only elements within one working set to show do the following:
+
* Set the view to show working sets as top-level elements.
+
* Use the ''Go Into'' action on the popup menu of the working set node in the view to scope the view down to just the working set.
+
 
+
== Focus the Java Browsing Perspective views ==
+
 
+
The leftmost toolbar button visible in the image below will toggle focus on the ''Packages'', ''Types'' and ''Members'' views of the ''Java Browsing Perspective''.
+
 
+
[[Image:Mylar-java-browsing.gif]]
+
 
+
= Team Support =
+
 
+
== Configuring the Synchronize view for change sets ==
+
 
+
There are two modes for Eclipse's Change Sets support: the '''models''' mode (Eclipse 3.2 and later) and the '''standard''' mode.  These modes are unrelated to Mylyn and apply to both Mylyn's automated Change Sets and the ones you can created manually in Eclipse.  Note that not all tools may support both modes.  The instructions below are for the CVS support included with Mylyn.  Refer to the Mylyn integration documentation for your source control plug-in for additional instructions for Mylyn change set integration, if available. 
+
 
+
The ''models'' mode is toggled via ''Synchronize View -> Preferences -> CVS -> Allow Models to participate in synchronizations''.  The Eclipse UI for ''Change Sets'' is not obvious so consider the following guidelines if you are having problems with it.
+
* Subclipse users: note that Subclipse 1.2.3 and later functions as if in the models mode described below, so the additional configuration step is not needed.
+
 
+
If you are using the '''standard''' mode, ''Change Sets'' toolbar button will only appear if the ''Synchronize'' view is in ''Incoming'' or ''Outgoing'' mode, not in the combined ''Incoming/Outgoing'' mode.  This button must be pressed in order for change sets to appear.  For working with CVS two modes are indistinguishable beyond this limitation.  Subclipse only supports the standard mode.  If you '''switch modes''' you must re-create your synchronization via the ''Synchronize...'' button available from the first toolbar button on the ''Synchronize'' view.
+
 
+
[[Image:mylar-changesets-subclipse.gif]]
+
 
+
If you are using the '''models''' mode, which is '''recommended''' if available for your team provider, you will notice that the Mylyn Active Change Sets work show up with a decoration in the lower-right corner, and that you can view both incoming and outgoing change sets at the same time. 
+
<!--However, note that there is a refresh problem with this mode ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=142395 bug 142395]).  To work around it, if a Change Set you expect is missing or if you get a "There are no more Incoming/Outgoing changes" message in the view on startup, toggle the third toolbar button between ''All Models'' and ''Change Sets''.  If that doesn't resolve it activate and deactivate the current task.-->
+
* '''Note:''' if you have enabled the ''models'' mode, but do not see the overlay icon visible in the screenshot below, it is because you are using an old non-models based synchronization.  Old synchronizations are not updated automatically when you switch modes so you must create a new one.
+
 
+
[[Image:mylar-changesets-model-based.gif]]
+
 
+
== Automatic change sets ==
+
 
+
Operations such as '''committing''', '''updating''', and '''patch creation''' can all be performed on Mylyn's automatically managed ''Change Sets''.  <code>Right+click</code> the change set node to get the corresponding ''Team'' menu.  Changed resources that are not a part of any task context will appear under the root of the ''Synchronize'' view.  If needed missing resources can be added to the task context ''Change Set'' via the ''Synchronize'' View by <code>right+clicking</code> the resource and selecting ''Add to'' and then selecting the corresponding task.
+
 
+
== Automatic commit messages ==
+
 
+
Mylyn will automatically generate commit messages for you when you use its Change Set support.  To modify the template go to ''Window -> Preferences -> Mylyn -> Team -> Commit Comment Templates''.
+
 
+
[[Image:mylar-commit-tempates.gif]]
+
 
+
== Working with patches ==
+
 
+
When applying patches, the preferred scenario is to have a task context attached to the task along with the patch.  Since this is not always feasible, Mylyn provides an action in the popup menu of the ''Synchronize'' view that supports adding changed elements to the task context. 
+
# Activate the task containing the patch.
+
# Apply the patch.  If yo uare using automatic change sets, this will cause the change set created by Mylyn to contain the outoing changes.  If it doesn't you can use the ''Add to'' action on the popup menu to add the elements to the corresponding change set.
+
# Invoke the ''Add to Task Context'' action on the change set node, causing all of the changed files to be added to the task context.  You can also invoke this action on a selection one or more elements (e.g. files) in the view.
+
 
+
[[Image:synchronize-view-add.gif]]
+
 
+
= Task Repository Connectors =
+
Mylyn allows you to collaborate on tasks via a shared task repository, also known as bug tracking systems.  In order to collaborate, you need to have a '''Connector''' to your particular repository.
+
 
+
Presently [[#Bugzilla_Connector|Bugzilla]], [[#JIRA_Connector|JIRA]], and [[#Trac_Connector|Trac]] are supported. To connect to unsupported repositories, see [[Mylyn_User_Guide#Generic_Web_Repository_Connector| Generic Web Repository Connectors]]. '''Also''', be sure to  [https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=anywordssubstr&short_desc=%5Bconnector%5D&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=&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= vote for your favourite Connector] to see it supported earlier, or [http://www.eclipse.org/mylyn/bugs.php create a new bug] if your issue tracker is not listed.
+
 
+
== Bugzilla Connector ==
+
 
+
Once Mylyn is installed there are a few steps involved to get up and running.
+
* To access tasks (reports/issues) on a repository such as Bugzilla you must first set up a ''Task Repository''
+
** Navigate to ''Window -> Show View -> Other -> Mylyn -> Task Repositories'' to open the ''Task Repositories'' view. Task Repositories view can also be launched via the Task List view menu.
+
** Launch the add repository wizard by pressing the add repository button located in the view's toolbar [[Image:Mylar-add-repository.png]].
+
** The first page of this wizard asks for the type of repository you wish to connect to (if you have installed multiple connectors). Select ''Bugzilla'' for example and press the ''Next'' button.
+
** On the second page you can enter the repository's address and your login credentials. After filling in these details, press the ''Validate'' button to ensure the repository exists and your login credentials are valid. Once the settings validate you can finish the wizard. The repository you added will be shown in the ''Task Repositories'' view.
+
[[Image:Mylar-repository-configuration.jpg|Repository Configuration]]
+
* Once the repository has been created, you may add queries to the Task List.
+
** In the ''Task List'' view right click anywhere in the list pane and select ''New Query'' from the context menu.
+
** Choose the repository you added in the previous steps.
+
** Enter query title and search criteria and then press ''Finish''.
+
** A query with the title you gave will appear in the Task List and will synchronize with the remote repository. If the query has hits they will appear within the query folder you've created.
+
** Double click to open a hit. Double click on the query to edit the query parameters.
+
** Click on the lightly shaded button (left of task icon) in the Task List to activate the task. Click again to deactivate.
+
 
+
See also [[Mylyn_FAQ#Bugzilla_Connector_troubleshooting| Bugzilla Connector Troubleshooting]].
+
 
+
 
+
=== Bugzilla Tasks ===
+
 
+
* If the Bugzilla task's severity is "major", "blocker", or "critical", the task icon in the Task List will be decorated with a red dot.
+
* If the Bugzilla task's severity is "enhancement" the task icon in the Task List will be decorated with a green triangle.
+
* Tasks will be colored green in the task list if they were resolved today and are owned by you. Unfortuantely Bugzilla does not have a notion of a completion date so we simply check the last comment timestamp and assume it to be the completion date (see {{bug|215342}}).
+
 
+
=== Tips for server administrators ===
+
 
+
Mylyn periodically checks config.cgi to retrieve the repository configuration.
+
On Eclipse.org this resulted in heavy CPU Load for the regeneration and a big surge in band width use.
+
* This configuration seldom changes so can be cached and served from a file instead of being regenerated every time.  While the size of this file tends to be small when hosting less than a dozen projects, it can be large on repositories holding large numbers of projects, e.g. 900K on bugs.eclipse.org.
+
* Generated bugzilla output contains a lot of unnecessary whitespace which can be trimmed before caching. For bugs.eclipse.org this reduces the file to about <em>660K</em>.
+
* The remaining file contains a lot of redundancy so can be gzipped for further reduction.  On bugs.eclipse.org this leaves about ''28K'', a considerable saving.
+
 
+
Mylyn has been modified to accept gzip encoding on all requests, and will do content negotiation. See [https://bugs.eclipse.org/bugs/show_bug.cgi?id=205708 bug 205708].
+
 
+
'''To add caching for your Bugzilla repository:'''
+
* Change the name of config.cgi to config-stock.cgi and get the caching code in a new config.cgi.
+
* The current version of this caching config.cgi script is hosted at:
+
  via CVS: :pserver:anonymous@dev.eclipse.org:/cvsroot/technology/org.eclipse.phoenix/infra-scripts/bugzilla/
+
  or: http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.phoenix/infra-scripts/bugzilla/?root=Technology_Project
+
* Modifications on this script are followed on [https://bugs.eclipse.org/bugs/show_bug.cgi?id=205416 bug 205416]
+
 
+
== Trac Connector ==
+
The Trac connector offers two access methods:
+
 
+
* '''Trac 0.9 and later''': In this mode the standard Trac web interface is used for repository access. Tickets may be created and edited through a web browser.
+
* '''XML-RPC Plugin''' (Trac trunk): This requires the latest revision (1175) of the [http://trac-hacks.org/wiki/XmlRpcPlugin XmlRpcPlugin] for Trac to be enabled for the accessed repository. The XmlRpcPlugin provides a remote interface to the Trac repository and is distributed separately from Trac (see [http://trac.edgewall.org/ticket/217 #217]). Currently, Trac and the XmlRpcPlugin need to be installed from source. See these [http://trac-hacks.org/wiki/XmlRpcPlugin#Installation install instructions] for requirements and documentation.
+
 
+
The Trac connector integrates Trac queries into the Task List. If you do not know your Trac repository version use the ''Automatic'' setting and click ''Validate Settings''.
+
 
+
 
+
'''New Task Editor'''
+
 
+
A rich editor for creating new Trac tasks is available for repositories that use XML-RPC (see the  [http://wiki.eclipse.org/index.php/Mylyn_FAQ FAQ] for XML-RPC configuration instructions).
+
 
+
[[Image:Trac-editor-new.gif]]
+
 
+
 
+
'''Rich Editor, Attachments and Offline support'''
+
 
+
The Trac connector supports the rich task editor.  Attributes and comments can be viewed and edited offline, synchronization is done in the background, and attachments can be posted and retrieved. 
+
 
+
Task Context attachments are supported via the context menu actions in the Task List.  This support requires the Trac XML-RPC plug-in to be enabled and the integration will fall back to the web mode if it is not, (see:  [http://wiki.eclipse.org/index.php/Mylyn_FAQ#Trac_Connector_troubleshooting Trac Connector troubleshooting]).
+
 
+
[[Image:Trac-editor.gif]]
+
 
+
== JIRA Connector ==
+
 
+
See [http://confluence.atlassian.com/display/JIRAEXT/Mylyn this page] for install instructions and additional screen shots. Note that the Mylyn JIRA connector requires at least JIRA version 3.3.3 and SOAP/RPC services have to be enabled on the server.
+
 
+
<b>Rich Editor</b>
+
 
+
The JIRA connector provides a rich editor, offline editing, and change notifications.
+
 
+
[[Image:Jira-editor.gif]]
+
 
+
<b>Search Integration</b>
+
 
+
Searching through JIRA repositories is integrated with the ''Search'' dialog.
+
 
+
[[Image:Jira-search.gif]]
+
 
+
<b>Query</b>
+
 
+
The JIRA query dialog has been streamlined into a single page.  Date range queries are now supported.
+
 
+
[[Image:Jira-query.gif]]
+
 
+
See also [[Mylyn_FAQ#JIRA_Connector_troubleshooting|JIRA Connector Troubleshooting]].
+
 
+
==  Generic Web Repository Connector ==
+
 
+
The generic web repository connector is NOT part of the default Mylyn install. You can install it from a separate extras update site. See [http://www.eclipse.org/mylyn/downloads/ Mylyn download page] for more details.
+
 
+
The web connector allow to retrieve tasks from repositories that don't have rich connectors, but can show list of tasks on the web UI. Out of the box connector provides configuration templates for the following issue tracking systems:
+
 
+
* Google Code Hosting (<code>code.google.com</code>)
+
* IssueZilla (<code>java.net, dev2dev, tigris.org</code>)
+
* GForge (<code>objectweb.org</code>)
+
* SourceForge (<code>sf.net</code>), see [[Using Sourceforge with Mylyn]]
+
* Mantis (<code>www.futureware.biz/mantis</code>)
+
* ChangeLogic (<code>changelogic.araneaframework.org</code>)
+
* OTRS (<code>otrs.org</code>)
+
* phpBB
+
* vBulletin
+
 
+
Lists of issues can be extracted from existing web pages using simple parsing configuration. Configuration can be also parametrized to make it easier to customize it for a specific project.
+
 
+
The parameters used for configuring project properties are typically substituted into the URLs used to access the repository. Substitution and matching rules can be edited under the ''Advanced Configuration'' section on both the ''Repository Settings'' page and the ''Edit Query'' page.
+
 
+
See [[Mylyn FAQ#Generic_Web_Repository_Connector|FAQ]] for the troubleshooting tips.
+
 
+
'''For example''', consider the configuration steps for GlassFish project at <code>java.net</code>:
+
 
+
'''1.''' Create new Generic web-based repository (in the Task Repository view). GlassFish is using IssueZilla and has a preconfigured template that can be selected by server url ''https://glassfish.dev.java.net/issues''. You can also specify all fields manually in the ''Advanced Configuration'' section. For GlassFish the following settings are required:
+
* Task URL: <code>${serverUrl}/show_bug.cgi?id=</code>
+
* New Task URL: <code>${serverUrl}/enter_bug.cgi?issue_type=DEFECT</code>
+
* Query URL: <code>${serverUrl}/buglist.cgi?component=glassfish&issue_status=NEW&issue_status=STARTED&issue_status=REOPENED&order=Issue+Number</code>
+
* Query Pattern: <code><nowiki><a href="show_bug.cgi\?id\=(.+?)">.+?<span class="summary">(.+?)</span></nowiki></code>
+
 
+
:'''Note:''' ''Query Pattern'' field should be a <code>regexp</code> with 1st matching group on ''Issue ID'' and 2nd on ''Issue Description''. Alternatively, you could use named matching groups: ({Id}.+?), ({Description}.+?), ({Status}.+?), ({Owner}.+?) and ({Type}.+?), then they can appear in query <code>regexp</code> in an arbitrary order. The second option requires build 2.0.0v20070717 or later.
+
 
+
:'''Note:''' the above fields are using parameter substitution <code>${..}</code>. Variables <code>serverUrl, userId</code> and <code>password</code> are substituted from the values of corresponding fields of the repository preference page. In addition you can specify any arbitrary parameters and their values that will be also substituted into the template fields.
+
 
+
:'''Note:''' the SourceForge template included with connector assume that ''single repository is used for all projects''. User should create multiple queries, and set project parameters at the query level. Because web connector don't support actions like "open repository task" there is really no need to create separate repositories per project and if you think about it that is how it work for connectors for Bugzilla and JIRA. However, it is still possible to setup separate repository per project using repository url like <nowiki>http://sourceforge.net/tracker/?group_id=172199</nowiki> and accordingly updating derived urls is the advanced repository settings.
+
 
+
<!-- TODO need login setup for above GlassFish example -->
+
'''For the web repository that require user to login, use advanced configuration in following way.'''
+
<i>This configuration is for GForge, you might need to change it for other repositories</i>:
+
 
+
* Login Request URL - an address that form is using to submit login request: <code>${serverUrl}/account/login.php?return_to=&form_loginname=${userId}&form_pw=${password}&login=Login '''(POST)'''</code>
+
* Login Form URL - an address where login form is located ''(only needed if server need a login token in the parameters of the Login Request URL)'': <code>${serverUrl}/account/login.php</code>
+
* Login Token Pattern - pattern to extract value of the <code>loginToken</code> parameter from the form page ''(only needed if server need a login token in the parameters of the Login Request URL and Login Form URL is specified)'': <code>session_ser=(.+?)</code>
+
 
+
'''2.''' Create a new query for the GlassFish task repository created above (either from popup context menu in the Task List view or using a "New..." wizard from File -> New... -> Other... menu).
+
 
+
*''Query URL'' and ''Query Pattern'' in the ''Repository Preferences'' are used as default query parameters and can be overwritten in ''Advanced Configuration'' section in ''Query Preferences''. Custom parameter values can also be overridden here as well as new parameters for substitution into the specific query.
+
 
+
*In the ''Advanced Configuration'' section of the "New Query" dialog, there is a "Preview" button. You can use it to test your query pattern.
+
 
+
[[Image:Generic-web-repository-settings.gif]]
+
 
+
== XPlanner Connector ==
+
 
+
The XPlanner connector is currently in the Experimental state.  It supports XPlanner version .7.
+
 
+
'''Query'''
+
 
+
XPlanner Connector supports creating queries from your XPlanner repository.  You can select to create a query for your own in progress tasks (the default), or select projects or iterations or user stories from a list.  You can also select ones assigned to you, or all.  Currently you can choose to group the results by tasks or user stories.  If you group the results by tasks, this will result in a single query with the applicable tasks underneath it.  If you choose to group the results by user stories, this will result in multiple queries added to the task list, each one corresponding to a user story, with the applicable tasks underneath it:
+
 
+
[[Image:XPlannerQuery.jpg]]
+
 
+
'''Task Editor'''
+
 
+
A rich editor for editing XPlanner tasks is available.  It currently doesn't support all of the attributes you can change in XPlanner itself, but allows you to modify the basic ones necessary for XP development -- e.g. summary, description, estimated time. The attributes section of the editor displays an XPlanner-like view of the meaningful attributes, some of which are not editable.
+
 
+
[[Image:XPlannerTaskEditor.gif]]
+
 
+
 
+
'''User Story Editor'''
+
 
+
If you open an XPlanner element by id, using the "Open Repository Task by Key/ID" dialog, and that id is a user story id, you will see the read-only user story editor.  This editor is just useful for seeing the major details of a user story -- no items in it can be changed, since there is no really good mapping between a user story and a Mylyn task.
+
 
+
[[Image:XPlannerUserStoryEditor.gif]]
+
 
+
= Integration with other tools =
+
 
+
See the '''[[Mylyn Extensions]]''' page for a listing of integration downloads.
+
 
+
Mylyn relies on [[Mylyn Architecture|Bridges]] to integrate the context model with the structure and UI features of domain-specific tools. To create a Bridge, see [[Mylyn_Integrator_Reference#Creating_Bridges| Creating Bridges]].
+
 
+
The core set of Bridges supports the Eclipse SDK (i.e. has bridges for Java, JUnit, PDE, Ant and Resources).  The Resources Bridge enables a basic level of interoperability with other tools that use files (e.g. <code>.php, .cpp</code>), and enables Mylyn filtering to work for generic views that show those files (i.e. the ''Project Explorer'', ''Navigator'') and any corresponding markers (i.e. the ''Problems'' and ''Tasks'' views).  This is only the most basic context model integration, and does not offer the benefits of a specialized structure bridge, such as making declarations part of the context and providing ''Active Search'' facilities.  Without a Bridge Mylyn cannot be applied to tool-specific views. 
+
 
+
'''If you would like to see support for a particular tool''', first do a search of the open bridge requests and [https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=anywordssubstr&short_desc=%5Bbridge%5D&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=&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= vote for the corresponding bug] if your tool is there, or [http://www.eclipse.org/mylyn/bugs.php create a new bug].  Also consider adding your experiences to the [[Mylyn_FAQ#Integration_with_other_tools | "Integration..."]] section of the Mylyn FAQ.
+
 
+
== Using Mylyn with WTP ==
+
 
+
Context modeling works at the file level, noting the limitation of [https://bugs.eclipse.org/bugs/show_bug.cgi?id=144882 bug 144882: interest filter fails on WTP Dynamic Web Project]
+
 
+
== External builders ==
+
 
+
If an external builder (e.g. Maven, pydev, or other Ant-based builders) is producing output files that are being automatically added to your context because they are not being marked "derived" as with Eclipse-based builders.  You may note that such files are always show as interesting when they are generated or updated and can not be filtered away, since Mylyn expects all files that have changed as part of the task context to have interest.
+
 
+
In this case you can explicitly exclude these files from being added to the task context the ''Preferences -> Mylyn -> Resources'' page.  For example, if the output folder of the builder is "target", you could set this the following way.  Similarly, you could add a filter for "*.pyc" to exclude all files generated with that extension.
+
 
+
Source code generators can be considered analogous since they produce intermediate files.  However, if you want to inspect the results of the source code generation after it is done you can avoid setting the exclusion.  Note that if a large number of files was generated not all generated files may be unfiltered.
+
 
+
[[Image:mylar-resource-exclusion.gif]]
+

Latest revision as of 11:12, 6 September 2023

The user guide has a new home

Back to the top