Jump to: navigation, search

Difference between revisions of "Mylyn/User Guide"

(Configuration)
 
(231 intermediate revisions by 36 users not shown)
Line 1: Line 1:
[[Category:Mylar]]
+
= Task List =
  
Also see: [http://www.eclipse.org/mylar/tips.php Tips & Tricks]
+
Use the Task List to view and manage your tasks. If the task list view is not visible, you can open it by navigating to Window -> Show View -> Other... -> Mylyn -> Task List. The Task List contains both "Local Tasks" and shared repository tasks that are stored in a task repository such as Bugzilla or Trac. Local tasks are typically contained in categories, which you can create by right-clicking on the task list and selecting New -> Category. Repository tasks are contained in special categories that represent queries.
= Introduction =
+
  
For '''tutorials and articles on using Mylar''' refer to the [http://www.eclipse.org/mylar/publications.php Publications page].  The role of this document is to provide up-to-date documentation on a listing of the key Mylar features and is not intended as a tutorial, and to allow users to contribute additional documentation.
+
[[Image:Feature-Reference-3.0-Task-List-Categorized1.png]]
  
Mylar is a task-focused UI for Eclipse that makes working with very large workspaces as easy as working with small ones.  Mylar 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).
+
At the top of the Task List, you will find the following buttons and features:
  
Once your tasks are integrated, Mylar monitors your work activity on those tasks to identify information relevant to the task-at-hand.  Mylar 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 importantFrom this, Mylar 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. Mylar 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, Mylar also facilitates multitasking, planning, reusing past efforts, and sharing expertise.
+
* '''New Task''' - Create a new local or repository task.
 +
* '''Synchronize''' - Update repository tasks with changes from the server.
 +
* '''Task Presentation''' - Toggle between Scheduled and Categorized presentations.
 +
* '''Focus on Workweek''' - See only tasks scheduled for this week.
 +
* '''Find''' - search for a task by typing in words from the task summary, or specify specific fields to querySee [[#Finding_Tasks | Finding Tasks]] for details.
 +
* '''Working set indicator''' - Indicates the currently active working set. Use the black arrow on the left to change the working set.
 +
* '''Current task indicator''' - Indicates the currently active task. Use the black arrow on the left to re-activate a recently active task.
  
= Installation =
+
== Finding Tasks ==
  
Also see the [[Mylar_FAQ#Installation_Troubleshooting | Installation FAQ]]
+
The task list can be filtered by providing a phrase to match against the task summary.  The phrase must appear in the summary of a task for the task to be visible when a filter is applied. The task list filter operates by searching on a locally-maintained index of the tasks in your task list. (In rare cases, it may be necessary to manually refresh the search index by selecting "Refresh Search Index" from the task list menu.)
  
To install Mylar, you need to
+
*Search for task summary or task id by entering the value. For example, <tt>NullPointerException</tt> or <tt>12345</tt>.
* [http://www.eclipse.org/downloads/ Download and install Eclipse 3.2 or 3.3Mx]
+
*Search for other task fields such as description or assignee by prefixing them with the field name. For example <tt>description:NullPointerException</tt> will search in the task description rather than the summary.  Content assist can be used to provide a list of common field names, and will provide a list of known user names when searching on user fields.
* [[#Platform requirements | Ensure you meet the platform requirements]]
+
[[Image:Task-list-index-reporter.png]]
* [[#Download | Download Mylar]]
+
*Search for date ranges by qualifying the range. For example, show tasks that were created in the <tt>(past week)</tt>.
After you have installed Mylar, there are a few more configuration steps that you might wish to do:
+
[[Image:Task-list-index-content-assist.png]]
* [[#General configuration]] for workspace setup recommendations
+
*Search for an exact phrase by enclosing it in double-quotes. For example, <tt>description:"user experience"</tt>.
* [[#Spell Checking]] shows how to enable spell-checking.
+
*Search for partial words by using the "*" wildcard. For example, <tt>exc*tion</tt> matches both "exclamation" and "exception".
* [[#Keyboard mappings on Linux]] shows how to set up some useful key bindings.
+
* [[#Task List backup and restore]] shows how to set up where backup files will be saved.
+
  
== Releases==  
+
=== Available Fields ===
  
The best and most stable release to use is always the latestThis 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 Mylar build that you install should be stable, including development builds. The UI of development builds can fluctuate.
+
Available fields can be found by using content assist in the search fieldThe following fields are available for search with most repositories:
 +
;content
 +
:match against any of summary, description, comments and other long text fields
 +
;summary
 +
:the task summary
 +
;description
 +
:match against the task description
 +
;person
 +
:match against any person field, such as reporter, assignee, watcher, etc.
 +
;task_key
 +
:match against the task or bug id
 +
;attachment
 +
:match against attachment names
 +
;assignee
 +
:match against the assignee of the task
 +
;reporter
 +
:match against the reporter of the task
 +
;product
 +
:match against the product of the task
 +
;component
 +
:match against the component of the task
 +
;creation_date
 +
:match against the date when the task was created
 +
;completion_date
 +
:match against the date when the task was completed
 +
;due_date
 +
:match against the date when the task is due
 +
;modification_date
 +
:match against the date when the task was last modified
 +
;status
 +
:match against the status
 +
;resolution
 +
:match against the resolution
 +
;severity
 +
:match against the severity
  
'''Schedule'''
+
Some fields listed above may not be available depending on the repository and connector.
  
* Dev builds
+
=== Search Operators ===
** Eclipse '''3.3''': available every Friday, often more frequently
+
** Eclipse '''3.2''': available 2 and 4 weeks after Milestone release date, or on request
+
* Eclipse milestone releases
+
** Day of the milestone release the dev build supports the latest milestone
+
** 1 week after the milestone release a new Mylar release is available
+
  
'''Dev Builds'''
+
The Task List provides logical operators. For example, <tt>NPE AND Display</tt>. Note that unlike other search phrases, '''search operators are case-sensitive'''; otherwise, the words are treated as part of the search phrase.
  
Development builds are released weekly, usually on Friday, and should be used by all Mylar contributors not using Mylar [http://wiki.eclipse.org/index.php/Mylar_Contributor_Reference#Self-hosting straight from CVS].
+
;AND
 +
:Searches for tasks that contain both words.
 +
;OR
 +
:Searches for tasks that contain at least one word.
  
* Eclipse '''3.3''': latest Eclipse milestone release is fully supported.
+
== Task List Presentation ==
* Eclipse '''3.2''': any 3.2.x version
+
  
'''Task List and Context Store Compatibility'''
+
The task list supports several ways to present tasks. You can toggle between the following modes by using the "Task Presentation" button in the toolbar.
 +
* '''Categorized''' - View tasks grouped by their category
 +
[[Image:Feature-Reference-3.0-Task-List-Presentation-Select-Categorized.png]]
  
The Task List and Context Store are compatible across all currently-supported Eclipse versions.  This means that you can use the same .mylar data in both Eclipse 3.2 and 3.3.  For Mylar versions that have reached their end-of-life we specify the update path so that the contents of the .mylar folder are updated.  This is listed in the "Update notes" on top of the [http://eclipse.org/mylar/doc/new.php New & Noteworthy].
 
  
'''Task context compatibility'''  
+
* '''Scheduled''' - View tasks grouped by the "''scheduled'' date"
 +
[[Image:Feature-Reference-3.0-Task-List-Presentation-Select-Scheduled.png]]
  
Task contexts can be shared with any previous released version of Mylar.  Note that if elements have been renamed they may not appear as interesting when the context is activated.
 
  
== Download ==
+
In either presentation, you can toggle the "Focus on Workweek" button. In this mode, only the following tasks will be visible:
 +
* Tasks scheduled for this week.
 +
* Overdue tasks.
 +
* Tasks with unread changes from your task repository.
  
For supported platforms and known limitations please see the [http://eclipse.org/mylar/dl.php Mylar download page].
+
== Icon Legend and Color Coding ==
  
The recommended way to install Mylar is from inside Eclipse:
+
See the legend below to interpret the icons and color coding in the task list. You can view this legend by selecting "Show UI Legend" from the menu that appears when you click the white down arrow next to the minimize button in the top right corner of the Task List view.  
# Select ''Help->Software Updates->Find and Install''.
+
# Select ''Search for new features to install'' and select ''Next''.
+
# Select ''New Remote Site''.
+
# Enter "Mylar" for the name and insert the download site given on the [http://www.eclipse.org/mylar/dl.php Mylar downloads page].  The URL should end up as something similar to <code>http://download.eclipse.org/technology/mylar/update-site/eX.Y.</code>  Select ''OK''.
+
# Make sure there is a check in the ''Mylar'' box, and select ''Finish''.
+
# Put a check in the box next to ''Mylar''. If you don't mind downloading some stuff you don't need, go ahead and select ''Next''.  Otherwise, expand the ''Mylar'' 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 Mylar without a bug repository, but it won't be as interesting an experience.
+
# 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''.
+
 
+
  
'''Errors you might get during the download process:'''
+
[[Image:Feature-Reference-3.0-UI-Legend.png]]
  
*'''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.  
+
== Creating New Tasks ==
  
*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.
+
[[Image:Feature-Reference-3.0-New-Task1.png]]
  
*You will probably get a warning that '''the feature is unsigned'''. If you trust that hackers have not befouled the Mylar plug-in, select ''Install All''.
+
You can create new tasks by clicking on the "New Task" button in the Task List's toolbar. This will open the "New Task" dialog and prompt you to select a repository. There are two main types of tasks, local tasks and repository tasks.
  
*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?)
+
=== Local Tasks ===
eclipse -clean --->
+
  
 +
Use local tasks if you do not have a shared task repository or if you would like to create a private, personal task that is local to your workspace. To create a local task, select '''Local Task''' and "Finish" from the New Task dialog.
  
 +
[[Image:Feature-Guide-3.0-Local-Task1.png]]
  
== Platform requirements==
+
You can then provide the following details about the task.
  
Mylar 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.
+
* '''Task Description - Your task is called "New Task" by default. Replace this with a brief task description.
 +
* '''Priority''' - Set the priority of your task. This will affect the task's icon and order in the task list.
 +
* '''Status''' - Set your task to "complete" or "incomplete". In your task list, completed tasks have a strikethrough font and will appear lower in the list.
 +
* '''URL''' - You can associate a URL with this task.
 +
** "Retrieve Task Description from URL" button - Set the task description to the title of the associated URL (page)
 +
** "Open with Web Browser" button - Open the URL in the integrated web browser
 +
* '''Scheduled For''' - Set the date when you will work on this task. Tasks scheduled for today or a date in the past will appear in blue in your task list. Tasks scheduled for future days will appear in black. If your task list is in focused mode, only tasks for the current week will be visible (unless they have unread changes).
 +
* '''Due''' - Set the date when your task must be completed. Overdue tasks and tasks due today will appear in red in your task list.
 +
* '''Estimated Hours''' - Estimate the number of hours it will take to complete this task.
 +
* '''Active''' - Displays the total time that you have worked on this task. Time is only recorded when this task is active and you are actively interacting with the system.
 +
* '''Notes''' - Record your personal notes about this task.
  
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].
+
=== Repository Tasks ===
* 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:
+
Create a new repository task when you would like to share information about the task with your team using a task repository such as Bugzilla or Trac. To create a new repository task, click on the "New Task" button in the Task List's toolbar. You can then select the repository where you would like to create a task. If you don't see your team's task repository, you will need to configure it in the task repositories view. Once you have selected a repository, click "Next". If you are connecting to a Bugzilla repository, select a "Product" as a top-level category for your task and click "Finish".
<code>
+
    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
+
</code>
+
  
<b> Linux and JVM issues</b>
+
[[Image:Feature-Guide-3.0-Repository-Task1.png]]
  
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.
+
A new task editor will appear. If you are using Bugzilla, you can enter the following information:
  
 +
Required
 +
* '''Description''' - Enter a brief task description in the text box at the top (this box does not have a label).
 +
* '''Component''' - Specify a "Component" to further categorize this task within the previously selected "Product".
 +
* '''Description''' - Describe the task in detail.
  
'''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:
+
Optional
export JAVA_HOME="''(location of JDK1.5 root)''"
+
* You can specify additional information about your tasks in the "Attributes" section.
export PATH=$JAVA_HOME/bin:$PATH
+
* '''Personal Planning''' - You can enter information in this section that will be local to your workspace and '''not''' available on your team's task repository. See "Local Tasks" for more information about the personal planning fields.
 +
* '''Assigned to''' - Specify who should work on the task. Type the first several characters of the person's email address, and then press ctrl+space to select the address from a list. A task can be assigned to only one person at a time.
 +
* '''Add CC''' - Add the addresses of people who should be notified of changes to this task. You can add multiple addresses, separated by a comma, e.g. (mik.kersten@tasktop.com, steffen.pingel@tasktop.com).
  
== Installing Browser on Linux ==
+
When finished, click "Submit" to add your new task to your team's shared task repository.
  
Mylar uses the Standard Widget Toolkit Browser, which means that there must be a browser on the system that works with the SWT Browser.  For Windows and MacOS, the standard works fine, but on some Linux distributions, you will need to download one.  '''Note:''' as of 3 Oct 2006, default Firefox distributions for Linux will not work; errors such as "Could not create Browser page: No more handles (<code>java.lang.UnsatisfiedLinkError: ...</code>)" may appear.
 
  
See [http://www.eclipse.org/swt/faq.php#browserlinux the SWT Browser guide] for which browsers will work.  
+
== Creating new Queries ==
  
[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)
+
[[Image:Feature-Reference-3.0-New-Query-Combined.png]]
  
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.
+
Once you have configured your team's task repository, you can use Queries to add tasks to your task list.
  
 +
* If the Task List is not visible, navigate to ''Window -> Show View -> Other -> Mylyn -> Task List''
 +
* Right-click on the Task List and select "New -> Query..."
 +
* Select the repository whose tasks you would like to download and click "Next".
 +
* If you are prompted to select a query type, select "Create query using form" and click "Next".
 +
* Complete the form to define which tasks will be downloaded as part of this query, and then click "Finish". You can provide values for only as many parameters as necessary to filter the query results.
  
* A quick work-around is to disable the internal browser pages in Mylar editors. To do this: ''Window -> Preferences -> Mylar -> Tasks -> Disable Internal Browser''.
+
If you are using the Bugzilla connector, you can specify the following parameters by default. The parameters for most other connectors will be similar.
*Before testing the browser support in Mylar, 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].
+
  
 +
* '''Query Title''' - Label that appears in your task list.
 +
* '''Summary''' - Specify words that must appear in the summary of tasks matched by this query.
 +
* '''Comment''' - Words that must appear in the comments of matching tasks.
 +
* '''Email''' - Specify all or part of an email address. This address is used together with the following options:
 +
** '''Owner''' - The specified email must match the person who the task is assigned to
 +
** '''Reporter''' - The specified email must match the person who created the task
 +
** '''CC''' - The person with the specified email address must be CC'd on the task
 +
** '''Commenter''' - The person with the specified email address must have commented on the task
 +
** You can choose from the following options to specify how the email address will be matched:
 +
*** '''substring''' - Only a part of the specified address must match
 +
*** '''exact''' - The specified email address must match exactly
 +
*** '''regexp''' - The email address must match the specified regular expression
 +
*** '''notregexp''' - The email address must NOT match the specified regular expression
 +
* '''Email 2''' - You can use this parameter to specify another email address to further restrict the results
 +
* '''Keywords''' - Click the "Select..." button to specify a keyword that must be associated with matching tasks
 +
* '''Product, Component, Version, ...''' - Optionally select parameters to restrict the results to a particular product, version, etc.
 +
* '''Update Attributes from Repository''' - Click this to refresh the available parameters if the project structure on the task respository has changed recently.
 +
* '''Changed in:''' - Only tasks modified within the specified number of days will appear in the query results
  
Mylar 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 Mylar's use of the internal browser via ''Preferences -> Mylar -> Tasks''.
 
  
The following steps have been verified on Fedora Core 5, and OpenSuSE 10.1.
+
== Scheduling ==
# 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
+
  
<code> 
+
Two kinds of dates for scheduling are provided.
    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
+
</code>
+
  
For Debian Etch and newer use the following MOZILLA_FIVE_HOME:
+
'''Scheduled Date'''
 +
* A soft date used for personal scheduling that can be easily deferred as priorities change. The scheduled date is the date you plan to start working on the task.
 +
* When a task reaches its scheduled date it will turn blue, indicating that the task should be activated and worked on today.
 +
* Scheduled dates are private to your local workspace
  
<code> 
+
'''Due Date'''
    MOZILLA_FIVE_HOME=/usr/lib/iceape
+
* A hard date when the task must be completed. This is often related to external constraints such as deadlines.
</code>
+
* If you are using a shared task repository, due dates become an attribute of the shared task and will be visible to other team members.
 +
* A task with a due date has a small clock overlay that is blue before the due date and red after.
  
:4. Log out and log in again (or type "<code>source .bashrc</code>" at the prompt)
+
== Synchronization ==
: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]
+
Repository tasks and queries are synchronized to reflect the latest changes on the server.  
 +
Tasks are synchronized the following ways:
  
'''Memory consumption problem with internal browser on Linux-GTK'''
+
* '''Automatic Synchronization.''' By default, tasks will be 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''
  
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])
+
* '''On Task Open.''' Tasks are synchronized automatically in the background when a task editor is opened.
  
== Installing on MacOS ==
+
* '''Manually.''' Individual tasks and queries can be synchronized manually by right-clicking on them in the Task List and selecting "Synchronize", or via the toolbar button. Clicking the toolbar button will synchronize all queries in your task list.
  
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 classpathPlease refer to and comment on [https://bugs.eclipse.org/bugs/show_bug.cgi?id=144287 bug 144287] if you see this problem.
+
<br>
<code>
+
'''Disconnected Mode'''<br>
    Could not create Bugzilla editor input
+
A task repository can be put into Disconnected mode via the right-click menu in the ''Task Repositories'' viewThis can be useful if the task repository is not currently in use (e.g. you are no longer engaged with the project, or the repository is no longer available). The 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. Note that it is not necessary to turn off synchronization or work in Disconnected Mode when working offline.
    java.io.IOException: SAX2 driver class org.apache.xerces.parsers.SAXParser not found
+
</code>
+
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 ==
+
== Incoming Changes ==
  
Mylar'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.
+
A blue arrow to the left of a task indicates that the task has changed in the shared repository. Double-click the task to view it in the task editor. Changes to the task will be highlighted in blue.
  
For example, to use Mylar as a rich client for Bugzilla:
+
To quickly review the differences since the task was last read, hover over the task in the Task List to view a summary in a tooltip. You can also press F4 to display a tooltip. You may also wish to view the task list in "Focus on Workweek" mode, which will filter out tasks without incoming changes that are not scheduled or due this week. You can toggle "Focus on Workweek" using a button in the Task List's toolbar.
* 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/mylar/dl.php Mylar download page] for installing the Task List and Bugzilla Connector.  Note that Mylar requires Java 5.
+
  
== Starting Mylar for the first time ==
 
Once everything has been installed, upon restarting, you will see a dialog box titled ''Mylar Recommended Preferences''.  It's probably best to accept the defaults unless you are already familiar with Mylar. 
 
  
Mylar introduces a number of views to the Eclipse workbench that can be found via Window->Show View->Other, under the ''Mylar'' category.
 
  
= Configuration =
+
== Reviewing Tasks ==
After you have installed Mylar, there are a number of things that you can configure to make your experience even richer.
+
  
== Recommended Eclipse settings ==
+
The task list has been carefully designed to support quickly reviewing tasks. Task reviewing is best done by configuring a query to show the tasks that you want to review. Once the tasks are displayed in the Task List they can be reviewed one at a time by scrolling through them using the keyboard up/down arrows. The task tooltip should provide enough detail to do a review and will display information relevant to the currently selected task.   
Recommendations for workspace configuration when using Mylar:
+
* '''Package Explorer'''
+
** Use flat layout in the Package Explorer (local pull down -> ''Layout -> Flat'').
+
** Link the Package Explorer with the editor (toolbar -> ''Link with Editor'').  With Mylar applied this won't cause the jumping around problems it typically does.
+
** Deselect the ''Referenced Libraries'' filter (local pull down -> ''Filters -> Referenced Libraries'').  With Mylar applied libraries won't blow up the tree.
+
** Leave the ''General -> Appearance -> Label Decorations -> Java Type Indicator'' off.  The type is visible under the Java file when Mylar is applied making such additional information redundant.
+
* '''Editors'''
+
** Turn comment folding on to reduce clutter when using auto folding (''Preferences -> Java -> Editor -> Folding'').
+
** Turn off or increase the number of editors to leave open (''Preferences -> General -> Editors -> Number of opened editors before closing''). Since Mylar will manage the open editors with task activation, this number can be set higher or automatic closing disabled entirely.
+
** If auto folding is used, the ''Outline'' view can be closed or made a fast view
+
* '''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.
+
  
=== Workspace setup ===
+
To edit the selected task press the enter key, use Ctrl+Enter to open the task in the background. To quickly jump to the next unread task hold down the Alt-key when pressing up or down. To mark a task as read while navigating use Alt+shift+up/down. When reviewing tasks in this way, it is best to avoid mouse-based and gesture-based scrolling.
  
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 Mylar 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.
 
* 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.
 
  
== Spell checking ==
+
[[Image:Feature-Reference-3.0-Task-List-Tooltip.png]]
  
Spell checking is supported in the task editor for local tasks and for connectors that support rich editing (e.g. Bugzilla, Trac).
+
== Task Progress Indicators ==
* 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]]
+
'''Weekly progress'''<br>
 +
When in ''Focus on Workweek'' mode (right-most toolbar button), the Task List will show a progress bar that indicates progress on the tasks scheduled for the current 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.
  
== Keyboard mappings on Linux ==
+
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.
  
If you are running Mylar on X-Windows, for example on Linux, FreeBSD, AIX and HP-UX, some keyboard bindings may not work by default.
+
[[Image:Feature-Reference-3.0-Weekly-Progress.png]]
  
If the <code>Ctrl+Alt+Shift+Arrow Up</code> shortcut for ''Mark as Landmark'' does not work do the following:
+
<br>
* ''Menu Bar -> Desktop -> Control Centre -> Keyboard Shortcuts -> Move one workspace up, Move one workspace down'': disable both.
+
'''Category Progress'''<br>
 +
You can hover over categories in the task list to display a tooltip that displays a summary of complete and incomplete tasks.
  
If <code>Alt+Click</code> quick unfiltering does not work try one of the following:
+
[[Image:Feature-Reference-3.0-Category-Progress.png]]
* 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>.
+
  
Also, see [[Mylar_Tips_and_Tricks#Keyboard_Shortcuts| keyboard shortcuts]].
+
== Task List Settings and Operations ==
  
= Task List =
+
Click the small white arrow in the top right of the Task List view to access the following settings:
 +
* '''Go Up to Root''' - Return to the normal presentation after previously selecting "Go Into" to see only the tasks in a particular category.
 +
* '''Sort''' - Open a dialog to set the sort order for the task list. This option is only available when the task list is not in "Focus on Workweek" mode.
 +
* '''Filter priority lower than''' - Hide tasks with a priority less than the priority you select. This option is only availabe when the task list is not in "Focus on Workweek" mode.
 +
* '''Filter completed tasks''' - Hide local and repository tasks that are in a completed state.
 +
* '''Search Repository''' - Opens a dialog to search for repository tasks. Search results will appear in a separate search results view.
 +
* '''Restore Tasks from History''' - Opens a dialog for restoring lost tasks.
 +
* '''Synchronize Changed''' - Updates the task list with any changes on the task repository.
 +
* '''Synchronize Automatically''' - When checked, the task list will update from the task repository on an interval specified in Window -> Preferences -> Mylyn -> Tasks
 +
* '''Show UI Legend''' - Displays a legend explaining icons and color-coding.
 +
* '''Focus on Workweek''' - Displays only tasks that are scheduled for this week, overdue, or have unread changes.
 +
* '''Link with Editor''' - Automatically selects the task corresponding to the active task editor.
 +
* '''Preferences''' - Access additional Task List preferences.
  
== Icon Legend ==
+
<br>
 +
Right-clicking in the task list provides access to the following operations
 +
* '''New...''' - Create new categories, queries, and tasks.
 +
* '''Open with Browser''' - Open the task in a web browser tab rather than the rich editor.
 +
* '''Schedule for''' - Set the soft date when you intend to work on the task.
 +
* '''Mark as''' - Mark a task as read or unread as you would an email message.
 +
* '''Copy Details''' - Places the task summary and html link in the clipboard so you can paste it into an email, document, etc.
 +
* '''Delete''' - Deletes local tasks. For repository tasks, the all downloaded data and local task information will be cleared but the task will re-appear if it still matches a query.
 +
* '''Rename''' - Rename a task.
 +
* '''Go into''' (queries only) - Show only the tasks in the selected category.
 +
* '''Import and Export''' - Access functionality for importing and exporting task data.
 +
* '''Repository''' (queries only) - Update repository settings
 +
* '''Synchronize''' - Update the selected tasks or queries from the shared task repository
 +
* '''Properties''' - Edit the settings for a repository query
  
Please see the [http://www.eclipse.org/mylar/tips.php Tips & Tricks page].
+
=  Task Repositories =
  
Also note the following connector-specific icons, which currently do not appear in the legend:
+
[[Image:Feature-Reference-3.0-Add-Task-Repository.png]]
* Bugzilla
+
** Green triangle: enhancement
+
** Red dot: major, critical or blocker
+
* Jira
+
** Icons correspond to issue type icons in the Web UI.
+
  
== 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. 
+
Use the Task Repositories view to configure Mylyn to connect to your team's shared task repository (bug or issue tracker):
  
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.
+
* Open the task repositories view by navigating to ''Window -> Show View -> Other -> Mylyn -> Task Repositories''  
 +
* Click the "Add Task Repository" button located in the view's toolbar.
 +
* Select the type of repository you wish to connect to and click "Next". If you don't see your repository type, you will need to install the appropriate connector.
 +
* 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, Click Finish. Note that the settings will vary somewhat depending on the type of repository that you are connecting to. The screenshot shows the settings fore connecting to a Bugzilla repository.
 +
* You should now see the new repository in the ''Task Repositories'' view.
 +
* Now that you have created a repository, you may add queries to the Task List.
  
[[Image:Weekly-progress.gif]]
+
= Task Editor =
  
== Progress for Categories ==
+
The task editor allows you to view and edit the tasks in your task list. Double-click on a task in your task list to open the editor. The features of the task editor will vary depending on whether it is a local task or a shared repository task. For shared repository tasks, there are some differences depending on the type of repository (and corresponding connector) that you are using (link: connectors).
  
Categories show progress for the number of completed tasks. 
+
== Repository Task Details ==
  
[[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.
+
In this section, we describe the task editor for shared bugs in a Bugzilla repository. Task editors for other repository types such as Trac offer similar functionality.
  
[[Image:Incoming-changes.gif]]
+
[[Image:Feature-Reference-3.0-Task-Editor-Top.png]]
  
== Task Repository Integration ==
+
'''Editor toolbar buttons'''
 +
* '''Synchronize Incoming Changes''' - Updates the local copy of the task to reflect any changes on the server.
 +
* '''Create a new subtask''' - Creates a new task that will be considered a prerequisite to completing the current task. Subtasks appear nested under their parent task in the task list. In Bugzilla terminology, the subtask "Blocks" the parent task and the subtask's ID will appear in the "Blocks:" field of the parent task.
 +
* '''History''' - Displays the task's change history in an internal browser using the web interface.
 +
* '''Open with Web Browser''' - Displays the web interface for the task in an internal web browser.
 +
* '''Find''' - Find text in comments, description, summary and private notes.
 +
* '''Activate''' - Toggles the activation and deactivation of the task.
  
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.
+
'''Attributes'''
 +
Use the Attributes section to add or update structured information about the task.
  
[[Image:Task-repository-integration.gif]]
+
'''Team Planning'''
 +
The Team Planning section contains time-related information about the task that will be shared with your team. You can use the '''Due''' field to set a due date for your task. On the due date, the task will appear in red in your task list.
  
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-128.ibm.com/developerworks/java/library/j-mylar1/ Task-focused programming with Mylar, Part 1], Querying a repository.
+
'''Attachments'''
 +
You can attach a file to this task so that a copy will be uploaded to your task repository and become available to anyone who can access the task.  
  
== Open Task dialog ==
+
To attach a file
 +
* click the "Attach..." button, which will open a wizard.
 +
* Select from one of the following:
 +
** '''File''' - Uploads a file from your system. Click "Browse" on the right to select the file.
 +
** '''Clipboard''' -
 +
** '''Workspace''' - Uploads a file from your workspace. Select the file from the box below.
 +
* Click next to enter attachment details:
 +
** '''Description''' - Provide a brief description of the file. This description will appear in the attachment list in the task editor.
 +
** '''Comment''' - Provide a comment about the file. This comment will appear in the comments section of the task editor.
 +
** '''Content Type''' - Optionally specify a content type for the file
 +
** '''Patch''' - Check this if the attachment is a source code patch file
 +
** '''Attach Context''' - Check this if you would also like to attach the context of your task. This context describes the resources that are most relevant to the task. If you attach a context, others can download it and focus the UI on the same resources that are relevant to you.
 +
** Click "Next" to preview your file. If your file is an image, a preview of the file will appear.
 +
** Click "Finish" to upload the file to the task repository. Files are uploaded without the need to click "submit" at the bottom of the task editor.
  
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]]
+
'''Duplicate Detection'''
 +
When submitting bug reports, you can avoid duplicates by clicking the "Search" button. This will search the repository for a stack trace that matches a stack trace in the task's Description field. The results of the duplicate detection show up in the Search view. If a match is found, you can open it and comment instead of creating a new bug report.
  
== Open Repository Task dialog ==
+
'''Comments'''
 +
Use this section to add new comments about the task and view all previous comments. Comments you have read previously are folded. You can expand and re-read individual comments or click the "+" at the top right to expand all comments.
  
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.
+
[[Image:Feature-Reference-3.0-Task-Editor-Bottom.png]]
  
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.
+
'''Actions'''
 +
Use this section to change the task's status or reassign the task to another person.
 +
* '''Attach Context''' - Uploads information about the resources that you have interacted with to the server. The context will appear in the attachments list so that others can download it and focus their UI on the resources that you found relevant for this task.
 +
* '''Submit''' - Submits all local changes to the task to your team's shared task repository.
  
Multiple tasks can be added simultaneously by informing a sequence of IDs, separated by commas, e.g. "1,2,3".
 
  
== Repository task attachments ==
+
'''People'''
 +
This section shows the people who are collaborating on the task.
 +
* '''Assigned to''' - This is the person who is responsible for completing the task
 +
* '''Reporter''' - This person created the task
 +
* '''QA Contact''' -
 +
* '''Add CC''' - Use this box to add new people to the "CC" list. People on the "CC" list will be notified of any changes to this task. To add a new person, type the start of their email address and then press ctrl+space to complete the address using content assist. You can add several addresses, separated with a comma.
 +
* '''CC''' - This box shows the people who are currently on the "CC" list. To remove a person, simply select their email address so that it is highlighted and click "Submit". You can hold down ctrl to select multiple people.
  
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.
+
== Context ==
  
[[Image:Repository-task-attachments.gif]]
+
The context tab allows you to manage the context of resources associated with the task. You can view the context tab by selecting it in the lower left of the editor window.
  
== Task List backup and restore ==
+
'''Elements'''<br>
 +
This section lists the resources that are part of the task's context. Because the number of elements may be large, you can adjust the level of detail using the slider at the top of the ''Actions'' section. Sliding the control all the way to the left will show you all elements in your task context. As you slide to the right, only the elements with a high level of interest will be displayed. You can manually remove elements from your task context by right-clicking and selecting "Remove From Context". You may choose to view all elements and prune irrelevant items in this way before attaching the context to the task so that others can download it.
  
'''Where does Mylar keep the task list?'''
+
'''Actions'''<br>
 +
* '''Element Detail Slider''' - Adjusts the minimum level of interest required for an element to be displayed in the ''Elements'' section.
 +
* '''Attach Context''' - Attaches the context to the task so that it is available for download from the shared task repository. The context consists of the elements shown on the right.
 +
* '''Retrieve Context''' - Replaces the current task context with one that is attached to the task in the shared task repository.
 +
* '''Copy Context to...''' - Copy the task context to another task. That task will then have the same context as the current task.
 +
* '''Clear Context.''' - Removes all context information from the task.
  
By default Mylar keeps your task list in <workspace>/.mylar/tasklist.xml.zip.  You can change this in the Mylar Task List preferences (''Window -> Preferences -> Mylar -> Task List -> Task Data'').
+
[[Image:Feature-Reference-3.0-Context-Tab.png]]
  
'''Where does Mylar keep the task list backups?'''
+
== Planning ==
  
By default, Mylar keeps the task list backups in the <code><workspace>/.mylar/backup</code> folder.
+
Use the planning tab to access local information about the task that is private to your workspace. You can view the planning tab by selecting it in the lower left of the editor window. This tab contains a large area where you can enter personal notes about the task. See the local task section for more information about fields in the Personal Planning section.
The location of this file, as well as backup scheduling, can be changed in ''Preferences -> Mylar -> Tasks'' in the ''Task Data -> Backup'' section.
+
  
'''How do I restore my task list from a backup?'''
+
[[Image:Feature-Reference-3.0-Planning-Tab.png]]
  
Task and context data can be restored from a backup snapshot zip file via  ''File -> Import -> Mylar Task Data''.  By default backup snapshots are taken daily and kept for 30 days.
+
= Task-Focused Interface =
  
[[Image:Tasklist-restore.gif]]
+
The task-focused interface is oriented around tasks and offers several ways to focus the interface on only what is relevant for the currently active task.
  
'''Can I create manual backups?'''
+
== Focusing Navigator Views ==
  
Yes. Use ''File -> Import/Export ->  Mylar Task Data''.
+
You can focus navigator views (e.g. Package Explorer, Project Explorer, Navigator) by toggling the "Focus on Active Task" button in the toolbar. When focused, the view will show only the resources that are "interesting" for the currently active task.
  
[[Image:mylar-tasklist-backup.gif]]
+
[[Image:Feature-Guide-3.0-Package-Explorer-Focused.png]]
  
'''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.
+
== Alt+Click Navigation / Show Filtered Children ==
  
'''If the Task List is blank''', either Mylar failed to install or update, or there was a problem reading the Task List.  By default Mylar keeps your Task List in <code><workspace>/.mylar/tasklist.xml</code>.  If you move workspaces, and have not changed the Mylar 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>.mylar</code> folder for a <code>tasklist-backup.xml</code> file, which will contain the previously-saved list.
+
To navigate to a new resource that is not a part of the active task's context, you can toggle "Focus on Active Task" off, browse to the resource, and then click "Focus on Active Task" again to see only relevant resources. A more efficient way to add new resources is to use Alt+Click navigation (clicking the mouse while holding the Alt key) or click the [+] icon that appears to the right of a tree node when the mouse hovers over it.
  
== Report Bugs from Error Log ==
+
When a view is in Focused mode, you can click the [+] icon to the right of a node, or Alt+Click the node, to temporarily show all of its children. 
 +
* Once an element that was previously not interesting is selected with the mouse, it becomes interesting and the other child elements will disappear. The clicked element is now a part of the task's context.
 +
* You can drill down multiple levels of filtered nodes by clicking the [+] icon to the right of each node you want to unfilter. Note that trying to expand the node in other ways (e.g. clicking the triangle to the left of the node) will not show its filtered children - clicking anywhere in the view (other than a [+] icon) will hide all filtered children again.
 +
* Alt can be held down while clicking to drill down from a top-level element to a deeply nested element that is to be added to the task context.
 +
* Multiple Alt+Clicks are supported so that you can add several elements to the task context. 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 normal click will cause uninteresting elements to disappear.  Note that Ctrl+clicked elements will become interesting (turn from gray to black) but only the most recently-clicked one will be selected while Alt is held down.
  
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:Show_filtered_children.png]]
  
[[Image:Report-bugs-error-log.gif]]
+
== Focusing Editors ==
  
== Automatic Duplicate Detection ==
+
Some editors such as the Java editor support focusing. Clicking the Focus button in the toolbar will fold all declarations that are not part of the active task context.
  
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:Feature-Guide-3.0-Focused-Editor.png]]
  
[[Image:Automatic-duplicate-detection.gif]]
+
== Task-focused Ordering ==
  
== Submitting Contexts ==
+
When a task is active, elements that are interesting are displayed more prominently. For example, when you open the Java Open Type dialog (Ctrl+Shift+T), types that are interesting for the active task are shown first. Similarly, when you use ctrl+space to autocomplete a method name in a Java source file, methods that are in the task context are displayed at the top.
  
When submitting comments, contexts can be attached by selecting the corresponding check-box in the ''Actions'' section.
+
== Working Set Integration ==
  
[[Image:Submitting-contexts.gif]]
+
When Focus is applied to a navigator view, the working sets filter for that navigator view will be disabled. This ensures that you see all interesting elements when working on a task that spans working sets. To enforce visibility of only elements within one working set, 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.
  
= Task-Focused UI =
+
== Open Task dialog ==
  
== Alt+Click navigation ==
+
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.
  
When a view is in Focused mode, you can Alt+Click a node in order to temporarily show all of it's children.
+
[[Image:Feature-Reference-3.0-Open-Task.png]]
* 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 single selection is made all uninteresting elements will disappear.
+
  
== Automatically toggle focus on navigator views ==
+
== Task Hyperlinking ==
 +
In the task editor, comments that include text of the form bug#123 or task#123 or bug 123 will be hyperlinked.  Ctrl+clicking on this text will open the task or bug in the rich task editor.
  
For navigator views (''Package Explorer'', ''Project Explorer'' and ''Navigator'') the ''Apply Mylar'' 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 -> Mylar -> Context.''
+
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. This is configured by right-clicking on the project and navigating to "Properties" > "Task Repository" and selecting the task repository used when working with this project.
  
[[Image:Auto-appy-mylar.gif]]
+
== Reporting Bugs from the Error Log ==
  
== Focus the Java Browsing Perspective views ==
+
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.
  
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:Feature-Reference-3.0-Error-Log.png]]
  
[[Image:Mylar-java-browsing.gif]]
+
= Team Support =
  
= Team Support =
+
The task-focused interface provides several ways to improve your work flow when working with a source code repository such as CVS or Subversion. CVS support is available out-of-the-box and task-focused interface integration for Subversion is available via the Subclipse or Subversive plugins.
  
== Configuring the Synchronize view for change sets ==
+
== Task-focused 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 Mylar and apply to both Mylar's automated Change Sets and the ones you can created manually in Eclipse.  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.
+
When working with a source code repository, you can commit or update only the resources that are in the context of a particular task. This helps you work on several tasks concurrently and avoid polluting your workspace with changes that are not relevant to the current task.
  
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.
+
To enable this functionality, locate the "Synchronize" view. If the view is not visible, you can open it by navigating to Window -> Show View -> Other... -> Team -> Synchronize. Next, click the small black arrow next to "Show File System Resources" in the Synchronize view toolbar and select "Change Sets". Note that change sets are not currently supported in the EGit connector.
  
[[Image:mylar-changesets-subclipse.gif]]
+
You can now synchronize resources in your workspace as usual (e.g. by right-clicking on a resource in the navigator and selecting "Team" -> "Synchronize with Repository". Your resources will now be grouped by change sets corresponding to tasks. Expanding the task shows individual resources. 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 right+clicking the resource and selecting "Add to" and then selecting the corresponding task. Select "no set" to remove a resource from a change set.
  
If you are using the '''models''' mode, you will notice that the Mylar 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.
+
[[Image:Feature-Reference-3.0-Change-Sets.png]]
* '''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]]
+
You can use buttons in the toolbar of the Synchronize view to change modes as follows:
 +
* '''Incoming Mode''' - See only updates to be retrieved from the server
 +
* '''Outgoing Mode''' - See only your local changes to be committed to the server
 +
* '''Incoming/Outgoing Mode''' - See both incoming and outgoing changes
  
== Automatic change sets ==
+
Right-clicking a Change Set provides access to the following operations:
  
Operations such as '''committing''', '''updating''', and '''patch creation''' can all be performed on Mylar'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.
+
* '''Add to Task Context''' - Adds all changed files to the active task context, see [[#Working with Patches]] for more information
 +
* '''Open Corresponding Task''' - Opens the task associated with the Change Set in the Task Editor
  
== Automatic commit messages ==
+
== Automatic Commit Messages ==
  
Mylar will automatically generate commit messages for you when you use its Change Set support. To modify the template go to ''Window -> Preferences -> Mylar -> Team -> Commit Comment Templates''.
+
When using task-focused change sets as described above, commit messages are automatically be generated based on the task whose resources are being commited. By default, the commit message includes information such as the task ID, description, and URL. To change the template for these commit messages, navigate to Window -> Preferences -> Mylyn -> Team.
  
[[Image:mylar-commit-tempates.gif]]
+
Note that for EGit, Task-focused Change Sets are not supported, however the commit message will be populated based on your currently active task.
  
= Task Repository Connectors =
+
== Working with Patches ==
Mylar 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 [[Mylar_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=Mylar&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/mylar/bugs.php create a new bug] if your issue tracker is not listed.
+
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 you are 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.
  
== Bugzilla Connector ==
+
[[Image:Feature-Reference-3.0-Add-To-Context.png]]
  
Once Mylar 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 -> Mylar -> Task Repositories'' to open the ''Task Repositories'' view.
 
** 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 [[Mylar_FAQ#Bugzilla_Connector_troubleshooting| Bugzilla Connector Troubleshooting]].
 
  
  
=== Bugzilla Tasks ===
+
= Shortcuts =
  
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.
+
<b>&nbsp;Task List view</b>
If the Bugzilla task's severity is "enhancement" the task icon in the Task List will be decorated with a green triangle.
+
<ul>
 +
<li>F2: rename</li>
 +
<li>F4: show tooltip</li>
 +
<li>F5: synchronize selected</li>
 +
<li>Alt + Down: go to next unread</li>
 +
<li>Alt + Up: go to previous unread</li>
 +
<li>Alt + Shift + C: mark complete (local tasks only)</li>
 +
<li>Alt + Shift + I: mark incomplete (local tasks only)</li>
 +
<li>Alt + Shift + R: mark as read</li>
 +
<li>Alt + Shift + U: mark as unread</li>
 +
<li>Esc: hide tooltip</li>
 +
<li>Enter: open task</li>
 +
<li>Insert: new local task</li>
 +
<li>Shift + Insert: new sub task</li>
 +
<li>Alt + N (Mac only): new local task</li>
 +
<li>Alt + Shift + N (Mac only): new sub task</li>
 +
<li>Ctrl+C: Copy details</li>
 +
<li>Ctrl+F: Find</li>
 +
<li>When dragging URLs to the Task List: in Mozilla/Firefox just drag, in Internet Explorer <code>Ctrl+drag</code></li>
 +
</ul>
  
== Trac Connector ==
+
<b>&nbsp;Task Editor</b>
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.
+
<ul>
* '''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.
+
<li>Ctrl+F: Find text in comments, description, summary and private notes</li>
 +
<li>Alt + Shift + C: mark complete (local tasks only)</li>
 +
<li>Alt + Shift + I: mark incomplete (local tasks only)</li>
 +
<li>Alt + Shift + R: mark as read</li>
 +
<li>Alt + Shift + U: mark as unread</li>
 +
</ul>
  
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''.
+
<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+Alt+Up</code>: mark as landmark</li>
 +
<li><code>Ctrl+Shift+Alt+Down</code>: mark less interesting</li>
 +
</ul>
  
'''New Task Editor'''
+
<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>
  
A rich editor for creating new Trac tasks is available for repositories that use XML-RPC (see the  [http://wiki.eclipse.org/index.php/Mylar_FAQ FAQ] for XML-RPC configuration instructions).
+
= Preferences =
  
[[Image:Trac-editor-new.gif]]
+
You can access the following Mylyn preference pages by navigating to Window -> Preferences -> Tasks.
  
 +
== Tasks ==
  
'''Rich Editor, Attachments and Offline support'''
+
* '''Synchronization''' - Set how often queries in your task list should update from your task repository. The default is 20 minutes.
 +
* '''Scheduling''' - Set the day when your week begins. This is used to determine whether tasks should appear as scheduled for this week.
 +
* '''Task Editing''' - Select whether tasks should be opened in the rich editor or an integrated browser window displaying the web interface for the task.
 +
<br>
 +
Click "Advanced" to reveal the following additional settings.
 +
* '''Task Timing''' - When a task is active, the time spent working on the task is recorded. If you check "Enable inactivity timeouts", time will not be accumulated while you are not actively working. You can set the number of minutes after which time will stop being accumulated toward the active task.
 +
* '''Task Data''' - Specify the location where your task list and task context data is stored.
  
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. 
+
== Context ==
  
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/Mylar_FAQ#Trac_Connector_troubleshooting Trac Connector troubleshooting]).
+
Use the following checkboxes to set your preferences for the task-focused interface.
  
[[Image:Trac-editor.gif]]
+
* '''Auto focus navigator view on task activation''' - Automatically toggle "Focus on Active Task" on when activating a task in navigation views such as the Package Explorer.
 +
* '''Auto expand tree views when focused''' - When toggling "Focus on Active Task", automatically expand trees so that all interesting elements are visible.
 +
* '''Manage open editors to match task context''' - When checked, activating a task will automatically open editors corresponding to the most interesting files in the task context. When deactivating a task, all editors will automatically close. While a task is active, files that become less interesting will automatically close as you work.
 +
* '''Remove file from context when editor is closed''' - When this option is checked, closing an editor will be considered an indication that you not interested in the corresponding file. Therefore, files you close will be removed from the task context. If you tend to close editors for files that you may want to return to, try unchecking this setting.
 +
* '''Open last used perspective on task activation''' - When this option is checked, activating a task will automatically switch to the perspective that was in use when the task was last active.
  
== JIRA Connector ==
+
== Resources ==
  
Note that the JIRA SOAP/RPC services have to be running on the server.  For additional details see the Requirements on the [http://jira-dashboard.tigris.org JIRA Dashboard] page.  For supported versions see the [http://www.eclipse.org/mylar/dl.php download page].
+
Use this preference page to add or remove resources that should not be included in the context of a task. Typically, excluded files are hidden backup or lock files that are not intented to be opened directly by the user of an application.
  
<b>Rich Editor</b>
+
== Breakpoints ==
  
The JIRA connector provides a rich editor, offline editing, and change notifications.
+
Use this preference page to enable breakpoints in context.
  
[[Image:Jira-editor.gif]]
+
* '''Include breakpoints in task context (Experimental)''' - When this option is checked, each task will have its own set of breakpoints which will be shared when you attach context to the task. Breakpoints created while a task is active will be removed from the workspace on task deactivation and restored the next time the task is activated. This feature has the following limitations (tracked on [https://bugs.eclipse.org/bugs/show_bug.cgi?id=428378 bug 428378]):
 +
** Breakpoints in closed projects are deleted from the context on task activation and cannot be recovered.
 +
** Breakpoints stored in context will not have their locations updated as the code changes, so they may be restored at the wrong location.
  
<b>Search Integration</b>
+
== Team ==
  
Searching through JIRA repositories is integrated with the ''Search'' dialog.
+
* '''Automatically create and manage with task context''' - Enables automatic change set management. Change sets will be created automatically so that you can commit or update only resources that are in a task's context.
 +
* '''Commit Message Template''' - Set the values that will appear in commit messages that are automatically generated when committing resources associated with a task. Pressing Ctrl+Space activates content assist which displays a list of the variables. Clicking once on a variable shows a description of that variable. For example, the variable ${task.id} provides the ID of the task associated with the commit.
  
[[Image:Jira-search.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.
 +
 
 +
See [[Mylyn/Extensions|Mylyn Extensions]] for a list of available connectors.
 +
 
 +
== Bugzilla Connector ==
 +
 
 +
* See the [[Mylyn/Bugzilla_Connector| Bugzilla Connector]] wiki page.
 +
* See [[Mylyn/FAQ#Bugzilla_Connector| Bugzilla Connector Troubleshooting]].
 +
 
 +
== Trac Connector ==
  
<b>Query</b>
+
See [[Mylyn/FAQ#Trac_Connector|Trac Connector Troubleshooting]].
  
The JIRA query dialog has been streamlined into a single page.  Date range queries are now supported.
 
  
[[Image:Jira-query.gif]]
 
  
See also [[Mylar_FAQ#JIRA_Connector_troubleshooting|JIRA Connector Troubleshooting]].
+
== Generic Web Templates Connector ==
  
==  Generic Web Repository Connector ==
+
The generic web repository connector is NOT part of the default Mylyn install. You can install it from the incubator update site. See the [http://www.eclipse.org/mylyn/downloads/ Mylyn download page] for more details.
  
The generic web repository connector is part of the Mylar install. It allows connection to repositories that are not currently supported by a rich connector. Out of the box it provides templates for the following issue tracking systems:
+
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>)
 
* Google Code Hosting (<code>code.google.com</code>)
 
* IssueZilla (<code>java.net, dev2dev, tigris.org</code>)
 
* IssueZilla (<code>java.net, dev2dev, tigris.org</code>)
 
* GForge (<code>objectweb.org</code>)
 
* GForge (<code>objectweb.org</code>)
* SourceForge (<code>sf.net</code>)
+
* SourceForge (<code>sf.net</code>), see [[Using Sourceforge with Mylyn]]
 
* Mantis (<code>www.futureware.biz/mantis</code>)
 
* Mantis (<code>www.futureware.biz/mantis</code>)
 
* ChangeLogic (<code>changelogic.araneaframework.org</code>)
 
* ChangeLogic (<code>changelogic.araneaframework.org</code>)
Line 478: Line 606:
 
* vBulletin
 
* vBulletin
  
Lists of issues can be retrieved from a web page using a simple template configuration. Templates can be also parametrized to make it easier to customize them for a specific project.
+
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.
 
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#Web_Templates_Connector|FAQ]] for the troubleshooting tips.
  
 
'''For example''', consider the configuration steps for GlassFish project at <code>java.net</code>:
 
'''For example''', consider the configuration steps for GlassFish project at <code>java.net</code>:
Line 490: Line 620:
 
* Query Pattern: <code><nowiki><a href="show_bug.cgi\?id\=(.+?)">.+?<span class="summary">(.+?)</span></nowiki></code>
 
* Query Pattern: <code><nowiki><a href="show_bug.cgi\?id\=(.+?)">.+?<span class="summary">(.+?)</span></nowiki></code>
  
*'''Note:''' ''Query Pattern'' field should have a <code>regexp</code> with 1st matching group on ''Issue ID'' and 2nd on ''Issue Description''.
+
:'''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 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 Trac. 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).
 
'''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).
Line 502: Line 642:
 
[[Image:Generic-web-repository-settings.gif]]
 
[[Image:Generic-web-repository-settings.gif]]
  
= Integration with other tools =
+
[[Category:Draft Documentation]]
 
+
'''Mylar can be integrated with other tools.''' Mylar relies on [[Mylar Architecture|Bridges]] to integrate the context model with the structure and UI features of domain-specific tools. To create a Bridge, see [[Mylar_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 Mylar 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 Mylar 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=Mylar&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/mylar/bugs.php create a new bug].  Also consider adding your experiences to the [[Mylar_FAQ#Integration_with_other_tools | "Integration..."]] section of the Mylar FAQ.
+
 
+
== Using Mylar 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]
+
 
+
== Maven and other external builders ==
+
 
+
If an external builder like Maven 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 can explicitly exclude these folders via the ''Preferences -> Mylar -> Resources'' page.  For example, if the output folder of the builder is "target", you could set this the following way:
+
 
+
[[Image:mylar-resource-exclusion.gif]]
+
 
+
== SVN integration via Subversive ==
+
 
+
Refer to [http://www.polarion.org/index.php?page=mylar&project=subversive Polarion's Mylar Integration Quick Start]
+
 
+
''NOTE: For release 0.9.2 and 1.0.0 the a Mylar integration plug-in must be downloaded from the Subversive update site.''
+
 
+
== SVN integration via Subclipse ==
+
 
+
For 1.0.0 the a Mylar integration plug-in must be downloaded from the Subclipse update site: <code>http://subclipse.tigris.org/update_1.2.x</code>
+
 
+
Supported features:
+
* Automatic Change Set management (see [[Mylar_FAQ#Team_Support|Mylar FAQ Team Support]])
+
* Automatic commit messages
+
* ''Open Corresponding Task'' action to open Mylar's task editor from the Change Set in ''Synchronize'' view and from entries in ''History'' view.
+
 
+
== PHP Development ==
+
 
+
If using the all-in-one package of [http://download.eclipse.org/tools/php/downloads/index.php?release=S20070101-RC1 PDT 0.7], it does not include the PDE Runtime Binary that is required by Mylar Focussed UI (1.0.1).  Get the PDE Runtime Binary [http://download.eclipse.org/eclipse/downloads/drops/R-3.2.1-200609210945/download.php?dropFile=eclipse-PDE-3.2.1.zip here] (link found on [http://download.eclipse.org/eclipse/downloads/drops/R-3.2.1-200609210945/index.php this page]).
+

Latest revision as of 15:00, 7 September 2016

Task List

Use the Task List to view and manage your tasks. If the task list view is not visible, you can open it by navigating to Window -> Show View -> Other... -> Mylyn -> Task List. The Task List contains both "Local Tasks" and shared repository tasks that are stored in a task repository such as Bugzilla or Trac. Local tasks are typically contained in categories, which you can create by right-clicking on the task list and selecting New -> Category. Repository tasks are contained in special categories that represent queries.

Feature-Reference-3.0-Task-List-Categorized1.png

At the top of the Task List, you will find the following buttons and features:

  • New Task - Create a new local or repository task.
  • Synchronize - Update repository tasks with changes from the server.
  • Task Presentation - Toggle between Scheduled and Categorized presentations.
  • Focus on Workweek - See only tasks scheduled for this week.
  • Find - search for a task by typing in words from the task summary, or specify specific fields to query. See Finding Tasks for details.
  • Working set indicator - Indicates the currently active working set. Use the black arrow on the left to change the working set.
  • Current task indicator - Indicates the currently active task. Use the black arrow on the left to re-activate a recently active task.

Finding Tasks

The task list can be filtered by providing a phrase to match against the task summary. The phrase must appear in the summary of a task for the task to be visible when a filter is applied. The task list filter operates by searching on a locally-maintained index of the tasks in your task list. (In rare cases, it may be necessary to manually refresh the search index by selecting "Refresh Search Index" from the task list menu.)

  • Search for task summary or task id by entering the value. For example, NullPointerException or 12345.
  • Search for other task fields such as description or assignee by prefixing them with the field name. For example description:NullPointerException will search in the task description rather than the summary. Content assist can be used to provide a list of common field names, and will provide a list of known user names when searching on user fields.

Task-list-index-reporter.png

  • Search for date ranges by qualifying the range. For example, show tasks that were created in the (past week).

Task-list-index-content-assist.png

  • Search for an exact phrase by enclosing it in double-quotes. For example, description:"user experience".
  • Search for partial words by using the "*" wildcard. For example, exc*tion matches both "exclamation" and "exception".

Available Fields

Available fields can be found by using content assist in the search field. The following fields are available for search with most repositories:

content
match against any of summary, description, comments and other long text fields
summary
the task summary
description
match against the task description
person
match against any person field, such as reporter, assignee, watcher, etc.
task_key
match against the task or bug id
attachment
match against attachment names
assignee
match against the assignee of the task
reporter
match against the reporter of the task
product
match against the product of the task
component
match against the component of the task
creation_date
match against the date when the task was created
completion_date
match against the date when the task was completed
due_date
match against the date when the task is due
modification_date
match against the date when the task was last modified
status
match against the status
resolution
match against the resolution
severity
match against the severity

Some fields listed above may not be available depending on the repository and connector.

Search Operators

The Task List provides logical operators. For example, NPE AND Display. Note that unlike other search phrases, search operators are case-sensitive; otherwise, the words are treated as part of the search phrase.

AND
Searches for tasks that contain both words.
OR
Searches for tasks that contain at least one word.

Task List Presentation

The task list supports several ways to present tasks. You can toggle between the following modes by using the "Task Presentation" button in the toolbar.

  • Categorized - View tasks grouped by their category

Feature-Reference-3.0-Task-List-Presentation-Select-Categorized.png


  • Scheduled - View tasks grouped by the "scheduled date"

Feature-Reference-3.0-Task-List-Presentation-Select-Scheduled.png


In either presentation, you can toggle the "Focus on Workweek" button. In this mode, only the following tasks will be visible:

  • Tasks scheduled for this week.
  • Overdue tasks.
  • Tasks with unread changes from your task repository.

Icon Legend and Color Coding

See the legend below to interpret the icons and color coding in the task list. You can view this legend by selecting "Show UI Legend" from the menu that appears when you click the white down arrow next to the minimize button in the top right corner of the Task List view.

Feature-Reference-3.0-UI-Legend.png


Creating New Tasks

Feature-Reference-3.0-New-Task1.png

You can create new tasks by clicking on the "New Task" button in the Task List's toolbar. This will open the "New Task" dialog and prompt you to select a repository. There are two main types of tasks, local tasks and repository tasks.

Local Tasks

Use local tasks if you do not have a shared task repository or if you would like to create a private, personal task that is local to your workspace. To create a local task, select Local Task and "Finish" from the New Task dialog.

Feature-Guide-3.0-Local-Task1.png

You can then provide the following details about the task.

  • Task Description - Your task is called "New Task" by default. Replace this with a brief task description.
  • Priority - Set the priority of your task. This will affect the task's icon and order in the task list.
  • Status - Set your task to "complete" or "incomplete". In your task list, completed tasks have a strikethrough font and will appear lower in the list.
  • URL - You can associate a URL with this task.
    • "Retrieve Task Description from URL" button - Set the task description to the title of the associated URL (page)
    • "Open with Web Browser" button - Open the URL in the integrated web browser
  • Scheduled For - Set the date when you will work on this task. Tasks scheduled for today or a date in the past will appear in blue in your task list. Tasks scheduled for future days will appear in black. If your task list is in focused mode, only tasks for the current week will be visible (unless they have unread changes).
  • Due - Set the date when your task must be completed. Overdue tasks and tasks due today will appear in red in your task list.
  • Estimated Hours - Estimate the number of hours it will take to complete this task.
  • Active - Displays the total time that you have worked on this task. Time is only recorded when this task is active and you are actively interacting with the system.
  • Notes - Record your personal notes about this task.


Repository Tasks

Create a new repository task when you would like to share information about the task with your team using a task repository such as Bugzilla or Trac. To create a new repository task, click on the "New Task" button in the Task List's toolbar. You can then select the repository where you would like to create a task. If you don't see your team's task repository, you will need to configure it in the task repositories view. Once you have selected a repository, click "Next". If you are connecting to a Bugzilla repository, select a "Product" as a top-level category for your task and click "Finish".

Feature-Guide-3.0-Repository-Task1.png

A new task editor will appear. If you are using Bugzilla, you can enter the following information:

Required

  • Description - Enter a brief task description in the text box at the top (this box does not have a label).
  • Component - Specify a "Component" to further categorize this task within the previously selected "Product".
  • Description - Describe the task in detail.

Optional

  • You can specify additional information about your tasks in the "Attributes" section.
  • Personal Planning - You can enter information in this section that will be local to your workspace and not available on your team's task repository. See "Local Tasks" for more information about the personal planning fields.
  • Assigned to - Specify who should work on the task. Type the first several characters of the person's email address, and then press ctrl+space to select the address from a list. A task can be assigned to only one person at a time.
  • Add CC - Add the addresses of people who should be notified of changes to this task. You can add multiple addresses, separated by a comma, e.g. (mik.kersten@tasktop.com, steffen.pingel@tasktop.com).

When finished, click "Submit" to add your new task to your team's shared task repository.


Creating new Queries

Feature-Reference-3.0-New-Query-Combined.png

Once you have configured your team's task repository, you can use Queries to add tasks to your task list.

  • If the Task List is not visible, navigate to Window -> Show View -> Other -> Mylyn -> Task List
  • Right-click on the Task List and select "New -> Query..."
  • Select the repository whose tasks you would like to download and click "Next".
  • If you are prompted to select a query type, select "Create query using form" and click "Next".
  • Complete the form to define which tasks will be downloaded as part of this query, and then click "Finish". You can provide values for only as many parameters as necessary to filter the query results.

If you are using the Bugzilla connector, you can specify the following parameters by default. The parameters for most other connectors will be similar.

  • Query Title - Label that appears in your task list.
  • Summary - Specify words that must appear in the summary of tasks matched by this query.
  • Comment - Words that must appear in the comments of matching tasks.
  • Email - Specify all or part of an email address. This address is used together with the following options:
    • Owner - The specified email must match the person who the task is assigned to
    • Reporter - The specified email must match the person who created the task
    • CC - The person with the specified email address must be CC'd on the task
    • Commenter - The person with the specified email address must have commented on the task
    • You can choose from the following options to specify how the email address will be matched:
      • substring - Only a part of the specified address must match
      • exact - The specified email address must match exactly
      • regexp - The email address must match the specified regular expression
      • notregexp - The email address must NOT match the specified regular expression
  • Email 2 - You can use this parameter to specify another email address to further restrict the results
  • Keywords - Click the "Select..." button to specify a keyword that must be associated with matching tasks
  • Product, Component, Version, ... - Optionally select parameters to restrict the results to a particular product, version, etc.
  • Update Attributes from Repository - Click this to refresh the available parameters if the project structure on the task respository has changed recently.
  • Changed in: - Only tasks modified within the specified number of days will appear in the query results


Scheduling

Two kinds of dates for scheduling are provided.

Scheduled Date

  • A soft date used for personal scheduling that can be easily deferred as priorities change. The scheduled date is the date you plan to start working on the task.
  • When a task reaches its scheduled date it will turn blue, indicating that the task should be activated and worked on today.
  • Scheduled dates are private to your local workspace

Due Date

  • A hard date when the task must be completed. This is often related to external constraints such as deadlines.
  • If you are using a shared task repository, due dates become an attribute of the shared task and will be visible to other team members.
  • A task with a due date has a small clock overlay that is blue before the due date and red after.

Synchronization

Repository tasks and queries are synchronized to reflect the latest changes on the server. Tasks are synchronized the following ways:

  • Automatic Synchronization. By default, tasks will be 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 Task Open. Tasks are synchronized automatically in the background when a task editor is opened.
  • Manually. Individual tasks and queries can be synchronized manually by right-clicking on them in the Task List and selecting "Synchronize", or via the toolbar button. Clicking the toolbar button will synchronize all queries in your task list.


Disconnected Mode
A task repository can be put into Disconnected mode via the right-click menu in the Task Repositories view. This can be useful if the task repository is not currently in use (e.g. you are no longer engaged with the project, or the repository is no longer available). The 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. Note that it is not necessary to turn off synchronization or work in Disconnected Mode when working offline.

Incoming Changes

A blue arrow to the left of a task indicates that the task has changed in the shared repository. Double-click the task to view it in the task editor. Changes to the task will be highlighted in blue.

To quickly review the differences since the task was last read, hover over the task in the Task List to view a summary in a tooltip. You can also press F4 to display a tooltip. You may also wish to view the task list in "Focus on Workweek" mode, which will filter out tasks without incoming changes that are not scheduled or due this week. You can toggle "Focus on Workweek" using a button in the Task List's toolbar.


Reviewing Tasks

The task list has been carefully designed to support quickly reviewing tasks. Task reviewing is best done by configuring a query to show the tasks that you want to review. Once the tasks are displayed in the Task List they can be reviewed one at a time by scrolling through them using the keyboard up/down arrows. The task tooltip should provide enough detail to do a review and will display information relevant to the currently selected task.

To edit the selected task press the enter key, use Ctrl+Enter to open the task in the background. To quickly jump to the next unread task hold down the Alt-key when pressing up or down. To mark a task as read while navigating use Alt+shift+up/down. When reviewing tasks in this way, it is best to avoid mouse-based and gesture-based scrolling.


Feature-Reference-3.0-Task-List-Tooltip.png

Task Progress Indicators

Weekly progress
When in Focus on Workweek mode (right-most toolbar button), the Task List will show a progress bar that indicates progress on the tasks scheduled for the current 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.

Feature-Reference-3.0-Weekly-Progress.png


Category Progress
You can hover over categories in the task list to display a tooltip that displays a summary of complete and incomplete tasks.

Feature-Reference-3.0-Category-Progress.png

Task List Settings and Operations

Click the small white arrow in the top right of the Task List view to access the following settings:

  • Go Up to Root - Return to the normal presentation after previously selecting "Go Into" to see only the tasks in a particular category.
  • Sort - Open a dialog to set the sort order for the task list. This option is only available when the task list is not in "Focus on Workweek" mode.
  • Filter priority lower than - Hide tasks with a priority less than the priority you select. This option is only availabe when the task list is not in "Focus on Workweek" mode.
  • Filter completed tasks - Hide local and repository tasks that are in a completed state.
  • Search Repository - Opens a dialog to search for repository tasks. Search results will appear in a separate search results view.
  • Restore Tasks from History - Opens a dialog for restoring lost tasks.
  • Synchronize Changed - Updates the task list with any changes on the task repository.
  • Synchronize Automatically - When checked, the task list will update from the task repository on an interval specified in Window -> Preferences -> Mylyn -> Tasks
  • Show UI Legend - Displays a legend explaining icons and color-coding.
  • Focus on Workweek - Displays only tasks that are scheduled for this week, overdue, or have unread changes.
  • Link with Editor - Automatically selects the task corresponding to the active task editor.
  • Preferences - Access additional Task List preferences.


Right-clicking in the task list provides access to the following operations

  • New... - Create new categories, queries, and tasks.
  • Open with Browser - Open the task in a web browser tab rather than the rich editor.
  • Schedule for - Set the soft date when you intend to work on the task.
  • Mark as - Mark a task as read or unread as you would an email message.
  • Copy Details - Places the task summary and html link in the clipboard so you can paste it into an email, document, etc.
  • Delete - Deletes local tasks. For repository tasks, the all downloaded data and local task information will be cleared but the task will re-appear if it still matches a query.
  • Rename - Rename a task.
  • Go into (queries only) - Show only the tasks in the selected category.
  • Import and Export - Access functionality for importing and exporting task data.
  • Repository (queries only) - Update repository settings
  • Synchronize - Update the selected tasks or queries from the shared task repository
  • Properties - Edit the settings for a repository query

Task Repositories

Feature-Reference-3.0-Add-Task-Repository.png


Use the Task Repositories view to configure Mylyn to connect to your team's shared task repository (bug or issue tracker):

  • Open the task repositories view by navigating to Window -> Show View -> Other -> Mylyn -> Task Repositories
  • Click the "Add Task Repository" button located in the view's toolbar.
  • Select the type of repository you wish to connect to and click "Next". If you don't see your repository type, you will need to install the appropriate connector.
  • 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, Click Finish. Note that the settings will vary somewhat depending on the type of repository that you are connecting to. The screenshot shows the settings fore connecting to a Bugzilla repository.
  • You should now see the new repository in the Task Repositories view.
  • Now that you have created a repository, you may add queries to the Task List.

Task Editor

The task editor allows you to view and edit the tasks in your task list. Double-click on a task in your task list to open the editor. The features of the task editor will vary depending on whether it is a local task or a shared repository task. For shared repository tasks, there are some differences depending on the type of repository (and corresponding connector) that you are using (link: connectors).

Repository Task Details

In this section, we describe the task editor for shared bugs in a Bugzilla repository. Task editors for other repository types such as Trac offer similar functionality.

Feature-Reference-3.0-Task-Editor-Top.png

Editor toolbar buttons

  • Synchronize Incoming Changes - Updates the local copy of the task to reflect any changes on the server.
  • Create a new subtask - Creates a new task that will be considered a prerequisite to completing the current task. Subtasks appear nested under their parent task in the task list. In Bugzilla terminology, the subtask "Blocks" the parent task and the subtask's ID will appear in the "Blocks:" field of the parent task.
  • History - Displays the task's change history in an internal browser using the web interface.
  • Open with Web Browser - Displays the web interface for the task in an internal web browser.
  • Find - Find text in comments, description, summary and private notes.
  • Activate - Toggles the activation and deactivation of the task.

Attributes Use the Attributes section to add or update structured information about the task.

Team Planning The Team Planning section contains time-related information about the task that will be shared with your team. You can use the Due field to set a due date for your task. On the due date, the task will appear in red in your task list.


Attachments You can attach a file to this task so that a copy will be uploaded to your task repository and become available to anyone who can access the task.

To attach a file

  • click the "Attach..." button, which will open a wizard.
  • Select from one of the following:
    • File - Uploads a file from your system. Click "Browse" on the right to select the file.
    • Clipboard -
    • Workspace - Uploads a file from your workspace. Select the file from the box below.
  • Click next to enter attachment details:
    • Description - Provide a brief description of the file. This description will appear in the attachment list in the task editor.
    • Comment - Provide a comment about the file. This comment will appear in the comments section of the task editor.
    • Content Type - Optionally specify a content type for the file
    • Patch - Check this if the attachment is a source code patch file
    • Attach Context - Check this if you would also like to attach the context of your task. This context describes the resources that are most relevant to the task. If you attach a context, others can download it and focus the UI on the same resources that are relevant to you.
    • Click "Next" to preview your file. If your file is an image, a preview of the file will appear.
    • Click "Finish" to upload the file to the task repository. Files are uploaded without the need to click "submit" at the bottom of the task editor.


Duplicate Detection When submitting bug reports, you can avoid duplicates by clicking the "Search" button. This will search the repository for a stack trace that matches a stack trace in the task's Description field. The results of the duplicate detection show up in the Search view. If a match is found, you can open it and comment instead of creating a new bug report.

Comments Use this section to add new comments about the task and view all previous comments. Comments you have read previously are folded. You can expand and re-read individual comments or click the "+" at the top right to expand all comments.

Feature-Reference-3.0-Task-Editor-Bottom.png

Actions Use this section to change the task's status or reassign the task to another person.

  • Attach Context - Uploads information about the resources that you have interacted with to the server. The context will appear in the attachments list so that others can download it and focus their UI on the resources that you found relevant for this task.
  • Submit - Submits all local changes to the task to your team's shared task repository.


People This section shows the people who are collaborating on the task.

  • Assigned to - This is the person who is responsible for completing the task
  • Reporter - This person created the task
  • QA Contact -
  • Add CC - Use this box to add new people to the "CC" list. People on the "CC" list will be notified of any changes to this task. To add a new person, type the start of their email address and then press ctrl+space to complete the address using content assist. You can add several addresses, separated with a comma.
  • CC - This box shows the people who are currently on the "CC" list. To remove a person, simply select their email address so that it is highlighted and click "Submit". You can hold down ctrl to select multiple people.

Context

The context tab allows you to manage the context of resources associated with the task. You can view the context tab by selecting it in the lower left of the editor window.

Elements
This section lists the resources that are part of the task's context. Because the number of elements may be large, you can adjust the level of detail using the slider at the top of the Actions section. Sliding the control all the way to the left will show you all elements in your task context. As you slide to the right, only the elements with a high level of interest will be displayed. You can manually remove elements from your task context by right-clicking and selecting "Remove From Context". You may choose to view all elements and prune irrelevant items in this way before attaching the context to the task so that others can download it.

Actions

  • Element Detail Slider - Adjusts the minimum level of interest required for an element to be displayed in the Elements section.
  • Attach Context - Attaches the context to the task so that it is available for download from the shared task repository. The context consists of the elements shown on the right.
  • Retrieve Context - Replaces the current task context with one that is attached to the task in the shared task repository.
  • Copy Context to... - Copy the task context to another task. That task will then have the same context as the current task.
  • Clear Context. - Removes all context information from the task.

Feature-Reference-3.0-Context-Tab.png

Planning

Use the planning tab to access local information about the task that is private to your workspace. You can view the planning tab by selecting it in the lower left of the editor window. This tab contains a large area where you can enter personal notes about the task. See the local task section for more information about fields in the Personal Planning section.

Feature-Reference-3.0-Planning-Tab.png

Task-Focused Interface

The task-focused interface is oriented around tasks and offers several ways to focus the interface on only what is relevant for the currently active task.

Focusing Navigator Views

You can focus navigator views (e.g. Package Explorer, Project Explorer, Navigator) by toggling the "Focus on Active Task" button in the toolbar. When focused, the view will show only the resources that are "interesting" for the currently active task.

Feature-Guide-3.0-Package-Explorer-Focused.png

Alt+Click Navigation / Show Filtered Children

To navigate to a new resource that is not a part of the active task's context, you can toggle "Focus on Active Task" off, browse to the resource, and then click "Focus on Active Task" again to see only relevant resources. A more efficient way to add new resources is to use Alt+Click navigation (clicking the mouse while holding the Alt key) or click the [+] icon that appears to the right of a tree node when the mouse hovers over it.

When a view is in Focused mode, you can click the [+] icon to the right of a node, or Alt+Click the node, to temporarily show all of its children.

  • Once an element that was previously not interesting is selected with the mouse, it becomes interesting and the other child elements will disappear. The clicked element is now a part of the task's context.
  • You can drill down multiple levels of filtered nodes by clicking the [+] icon to the right of each node you want to unfilter. Note that trying to expand the node in other ways (e.g. clicking the triangle to the left of the node) will not show its filtered children - clicking anywhere in the view (other than a [+] icon) will hide all filtered children again.
  • Alt can be held down while clicking to drill down from a top-level element to a deeply nested element that is to be added to the task context.
  • Multiple Alt+Clicks are supported so that you can add several elements to the task context. 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 normal click will cause uninteresting elements to disappear. Note that Ctrl+clicked elements will become interesting (turn from gray to black) but only the most recently-clicked one will be selected while Alt is held down.

Show filtered children.png

Focusing Editors

Some editors such as the Java editor support focusing. Clicking the Focus button in the toolbar will fold all declarations that are not part of the active task context.

Feature-Guide-3.0-Focused-Editor.png

Task-focused Ordering

When a task is active, elements that are interesting are displayed more prominently. For example, when you open the Java Open Type dialog (Ctrl+Shift+T), types that are interesting for the active task are shown first. Similarly, when you use ctrl+space to autocomplete a method name in a Java source file, methods that are in the task context are displayed at the top.

Working Set Integration

When Focus is applied to a navigator view, the working sets filter for that navigator view will be disabled. This ensures that you see all interesting elements when working on a task that spans working sets. To enforce visibility of only elements within one working set, 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.

Open Task dialog

An Open Type style dialog is available for opening tasks (Ctrl+F12) and for activating tasks (Ctrl+F9). The list is initially populated by recently active tasks. The active task can also be deactivated via Ctrl+Shift+F9. 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.

Feature-Reference-3.0-Open-Task.png

Task Hyperlinking

In the task editor, comments that include text of the form bug#123 or task#123 or bug 123 will be hyperlinked. Ctrl+clicking on this text will open the task or bug in the rich task editor.

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. This is configured by right-clicking on the project and navigating to "Properties" > "Task Repository" and selecting the task repository used when working with this project.

Reporting Bugs from the 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.

Feature-Reference-3.0-Error-Log.png

Team Support

The task-focused interface provides several ways to improve your work flow when working with a source code repository such as CVS or Subversion. CVS support is available out-of-the-box and task-focused interface integration for Subversion is available via the Subclipse or Subversive plugins.

Task-focused Change Sets

When working with a source code repository, you can commit or update only the resources that are in the context of a particular task. This helps you work on several tasks concurrently and avoid polluting your workspace with changes that are not relevant to the current task.

To enable this functionality, locate the "Synchronize" view. If the view is not visible, you can open it by navigating to Window -> Show View -> Other... -> Team -> Synchronize. Next, click the small black arrow next to "Show File System Resources" in the Synchronize view toolbar and select "Change Sets". Note that change sets are not currently supported in the EGit connector.

You can now synchronize resources in your workspace as usual (e.g. by right-clicking on a resource in the navigator and selecting "Team" -> "Synchronize with Repository". Your resources will now be grouped by change sets corresponding to tasks. Expanding the task shows individual resources. 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 right+clicking the resource and selecting "Add to" and then selecting the corresponding task. Select "no set" to remove a resource from a change set.

Feature-Reference-3.0-Change-Sets.png

You can use buttons in the toolbar of the Synchronize view to change modes as follows:

  • Incoming Mode - See only updates to be retrieved from the server
  • Outgoing Mode - See only your local changes to be committed to the server
  • Incoming/Outgoing Mode - See both incoming and outgoing changes

Right-clicking a Change Set provides access to the following operations:

  • Add to Task Context - Adds all changed files to the active task context, see #Working with Patches for more information
  • Open Corresponding Task - Opens the task associated with the Change Set in the Task Editor

Automatic Commit Messages

When using task-focused change sets as described above, commit messages are automatically be generated based on the task whose resources are being commited. By default, the commit message includes information such as the task ID, description, and URL. To change the template for these commit messages, navigate to Window -> Preferences -> Mylyn -> Team.

Note that for EGit, Task-focused Change Sets are not supported, however the commit message will be populated based on your currently active task.

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.

  1. Activate the task containing the patch.
  2. Apply the patch. If you are 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.
  3. 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.

Feature-Reference-3.0-Add-To-Context.png



Shortcuts

 Task List view

  • F2: rename
  • F4: show tooltip
  • F5: synchronize selected
  • Alt + Down: go to next unread
  • Alt + Up: go to previous unread
  • Alt + Shift + C: mark complete (local tasks only)
  • Alt + Shift + I: mark incomplete (local tasks only)
  • Alt + Shift + R: mark as read
  • Alt + Shift + U: mark as unread
  • Esc: hide tooltip
  • Enter: open task
  • Insert: new local task
  • Shift + Insert: new sub task
  • Alt + N (Mac only): new local task
  • Alt + Shift + N (Mac only): new sub task
  • Ctrl+C: Copy details
  • Ctrl+F: Find
  • When dragging URLs to the Task List: in Mozilla/Firefox just drag, in Internet Explorer Ctrl+drag

 Task Editor

  • Ctrl+F: Find text in comments, description, summary and private notes
  • Alt + Shift + C: mark complete (local tasks only)
  • Alt + Shift + I: mark incomplete (local tasks only)
  • Alt + Shift + R: mark as read
  • Alt + Shift + U: mark as unread

 General

  • Alt+click or Alt+RightArrow: 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.
  • Ctrl+Shift+Alt+RightArrow Quick Context View
  • Ctrl+F9: activate task dialog
  • Ctrl+Shift+F9: deactivate task
  • Ctrl+F12: open task dialog
  • Ctrl+Shift+F12: open repository task dialog

 Interest manipulation

  • Ctrl+Shift+Alt+Up: mark as landmark
  • Ctrl+Shift+Alt+Down: mark less interesting

 Useful Eclipse shortcuts

  • Alt+Shift+Q, K: show Task List view
  • Ctrl+F10: invoke view menu or ruler menu in editor

Preferences

You can access the following Mylyn preference pages by navigating to Window -> Preferences -> Tasks.

Tasks

  • Synchronization - Set how often queries in your task list should update from your task repository. The default is 20 minutes.
  • Scheduling - Set the day when your week begins. This is used to determine whether tasks should appear as scheduled for this week.
  • Task Editing - Select whether tasks should be opened in the rich editor or an integrated browser window displaying the web interface for the task.


Click "Advanced" to reveal the following additional settings.

  • Task Timing - When a task is active, the time spent working on the task is recorded. If you check "Enable inactivity timeouts", time will not be accumulated while you are not actively working. You can set the number of minutes after which time will stop being accumulated toward the active task.
  • Task Data - Specify the location where your task list and task context data is stored.

Context

Use the following checkboxes to set your preferences for the task-focused interface.

  • Auto focus navigator view on task activation - Automatically toggle "Focus on Active Task" on when activating a task in navigation views such as the Package Explorer.
  • Auto expand tree views when focused - When toggling "Focus on Active Task", automatically expand trees so that all interesting elements are visible.
  • Manage open editors to match task context - When checked, activating a task will automatically open editors corresponding to the most interesting files in the task context. When deactivating a task, all editors will automatically close. While a task is active, files that become less interesting will automatically close as you work.
  • Remove file from context when editor is closed - When this option is checked, closing an editor will be considered an indication that you not interested in the corresponding file. Therefore, files you close will be removed from the task context. If you tend to close editors for files that you may want to return to, try unchecking this setting.
  • Open last used perspective on task activation - When this option is checked, activating a task will automatically switch to the perspective that was in use when the task was last active.

Resources

Use this preference page to add or remove resources that should not be included in the context of a task. Typically, excluded files are hidden backup or lock files that are not intented to be opened directly by the user of an application.

Breakpoints

Use this preference page to enable breakpoints in context.

  • Include breakpoints in task context (Experimental) - When this option is checked, each task will have its own set of breakpoints which will be shared when you attach context to the task. Breakpoints created while a task is active will be removed from the workspace on task deactivation and restored the next time the task is activated. This feature has the following limitations (tracked on bug 428378):
    • Breakpoints in closed projects are deleted from the context on task activation and cannot be recovered.
    • Breakpoints stored in context will not have their locations updated as the code changes, so they may be restored at the wrong location.

Team

  • Automatically create and manage with task context - Enables automatic change set management. Change sets will be created automatically so that you can commit or update only resources that are in a task's context.
  • Commit Message Template - Set the values that will appear in commit messages that are automatically generated when committing resources associated with a task. Pressing Ctrl+Space activates content assist which displays a list of the variables. Clicking once on a variable shows a description of that variable. For example, the variable ${task.id} provides the ID of the task associated with the commit.

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.

See Mylyn Extensions for a list of available connectors.

Bugzilla Connector

Trac Connector

See Trac Connector Troubleshooting.


Generic Web Templates Connector

The generic web repository connector is NOT part of the default Mylyn install. You can install it from the incubator update site. See the 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.google.com)
  • IssueZilla (java.net, dev2dev, tigris.org)
  • GForge (objectweb.org)
  • SourceForge (sf.net), see Using Sourceforge with Mylyn
  • Mantis (www.futureware.biz/mantis)
  • ChangeLogic (changelogic.araneaframework.org)
  • OTRS (otrs.org)
  • 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 FAQ for the troubleshooting tips.

For example, consider the configuration steps for GlassFish project at java.net:

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: ${serverUrl}/show_bug.cgi?id=
  • New Task URL: ${serverUrl}/enter_bug.cgi?issue_type=DEFECT
  • Query URL: ${serverUrl}/buglist.cgi?component=glassfish&issue_status=NEW&issue_status=STARTED&issue_status=REOPENED&order=Issue+Number
  • Query Pattern: <a href="show_bug.cgi\?id\=(.+?)">.+?<span class="summary">(.+?)</span>
Note: Query Pattern field should be a regexp 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 regexp in an arbitrary order. The second option requires build 2.0.0v20070717 or later.
Note: the above fields are using parameter substitution ${..}. Variables serverUrl, userId and password 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 Trac. However, it is still possible to setup separate repository per project using repository url like http://sourceforge.net/tracker/?group_id=172199 and accordingly updating derived urls is the advanced repository settings.

For the web repository that require user to login, use advanced configuration in following way. This configuration is for GForge, you might need to change it for other repositories:

  • Login Request URL - an address that form is using to submit login request: ${serverUrl}/account/login.php?return_to=&form_loginname=${userId}&form_pw=${password}&login=Login (POST)
  • 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): ${serverUrl}/account/login.php
  • Login Token Pattern - pattern to extract value of the loginToken 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): session_ser=(.+?)

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.

Generic-web-repository-settings.gif