Skip to main content

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

Jump to: navigation, search

Difference between revisions of "Mylyn/User Guide"

(Keyboard mappings on Linux)
(Replaced content with "[https://github.com/eclipse-mylyn/org.eclipse.mylyn/wiki/User-Guide The user guide has a new home]")
 
(297 intermediate revisions by 43 users not shown)
Line 1: Line 1:
[[Category:Mylar]]
+
[https://github.com/eclipse-mylyn/org.eclipse.mylyn/wiki/User-Guide The user guide has a new home]
* For troubleshooting, also see the [[Mylar_FAQ|Mylar FAQ]].
+
 
+
= Introduction =
+
 
+
'''What is Mylar?'''
+
 
+
Mylar is a task-focused UI for Eclipse that makes working with very large workspaces as easy as working with small ones. It makes tasks a first class part of Eclipse, and integrates task repositories such as Bugzilla, Trac, and JIRA. Once your tasks are integrated, Mylar monitors your work activity to identify information relevant to the task-at-hand. Mylar uses this task context to focus the Eclipse UI on the interesting information, hide the uninteresting, and automatically find what's related.
+
 
+
'''How does Mylar tell what elements are relevant or ''interesting''?'''
+
 
+
Mylar monitors Eclipse and captures your interaction in a task context. Files, types, methods, and fields -- each gets assigned a degree of interest based on how recently and frequently you interact with that element.  This results in uninteresting elements being filtered from view within Eclipse, allowing you to focus on on what is important.
+
 
+
= Quick Installation Guide =
+
To install Mylar, you need to
+
* Download and install Eclipse.  We recommend using a stable version of Eclipse, but it must be '''at least Eclipse 3.1'''.  See the [http://www.eclipse.org/downloads/ Eclipse download site].
+
* [[#Download Mylar]]. 
+
* [[#Download Required Applications]], if needed.  '''Mylar needs the Java 5 Virtual Machine and a browser that works with Eclipse'''.
+
 
+
 
+
After you have installed Mylar, there are a few more configuration steps that you might wish to do:
+
* [[#General configuration]] for workspace setup recommendations
+
* [[#Spell Checking]] shows how to enable spell-checking.
+
* [[#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.
+
 
+
= Installation Guide =
+
 
+
== Download Mylar ==
+
For supported platforms and known limitations please see the [http://eclipse.org/mylar/dl.php Mylar download page].
+
 
+
The recommended way to install Mylar is from inside Eclipse:
+
# Select ''Help->Software Updates->Find and Install''.
+
# Select ''Search for new features to install'' and select ''Next''.
+
# Select ''New Remote Site''.
+
# Enter "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:'''
+
 
+
*'''Network connection problems encountered during search''' means that Eclipse couldn't find the location you entered.  This might be because you copied something incorrectly (watch for extra characters -- even extra spaces can cause errors), or because the site went down.  You might be able to see if the site is down by copying the URL into your Web browser.
+
 
+
*''' Update manager failure''' means that Eclipse could not access the update site, or that it got confused about the configuration state of your Eclipse.  First try updating again to see if the update site is accessible. 
+
 
+
*If you are trying to update the JIRA connector you can also try de-selecting that feature in case the Tigris.org update site is not accessible.  Using use ''Search for new features..'' when installing can help to avoid this problem.  If that does not work see the [[#Configuration| feature configuration troubleshooting]] below.
+
 
+
*You will probably get a warning that '''the feature is unsigned'''.  If you trust that hackers have not befouled the Mylar plug-in, select ''Install All''.
+
 
+
*You will get a dialog box asking if you would like to restart Eclipse.  We recommend that you select ''Yes''.  <!--- If you are running Eclipse from the command line, it might be worthwhile to start it once with  (@@@? true?)
+
eclipse -clean --->
+
 
+
== Download Required Applications ==
+
 
+
Mylar needs the '''Java 5''' virtual machine. (You do not need to use the 1.5 compiler, just the '''1.5 VM'''.)  You also need a '''web browser that works with the Standard Widget Toolkit'''; Windows and MacOS users are fine, but Linux users might have to download another [[#Installing_Browser_on_Linux|browser]].
+
 
+
== Download and configure Java 5 or 6 ==
+
To check the version of the Java virtual machine that Eclipse was launched with to to ''Help -> About Eclipse SDK -> Configuration Details'' and verify that the java.vm.version is 1.5. 
+
 
+
Mac users should refer to the last comment on [https://bugs.eclipse.org/bugs/show_bug.cgi?id=116347#c4 bug 1163477] for instructions on how to change the 1.4 default.
+
 
+
* If you do not have Java 5, you can download it from [http://72.5.124.55/javase/downloads/index.jsp Sun's web site].
+
* If you have more than one VM, you need to specify that Eclipse should use the JDK1.5 VM. 
+
 
+
 
+
<b>We do [https://bugs.eclipse.org/bugs/show_bug.cgi?id=140955 not recommend] using JDK 1.6 on Eclipse 3.1.</b> (It works fine with Eclipse 3.2 or 3.3.) To use JDK 1.6 on Eclipse 3.1, you must add the following line to your config.ini file:
+
<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>
+
 
+
For those experiencing unstable performance with Linux using the Sun JVM, download the [http://www-128.ibm.com/developerworks/java/jdk/linux/download.html IBM JVM], which will require you to register with IBM prior to download.
+
 
+
 
+
'''In Unix''', set the environment variable <code>JAVA_HOME</code> to the root of the JDK1.5 installation and/or set the <code>PATH</code> variable to put the JDK1.5 executable directory before any other VM executable directories.  For example, under <code>bash</code> in Unix:
+
export JAVA_HOME="''(location of JDK1.5 root)''"
+
export PATH=$JAVA_HOME/bin:$PATH
+
 
+
== Installing Browser on Linux ==
+
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. 
+
 
+
To test to see if your browser is properly configured, select ''Window -> Show View -> Other -> General -> Internal Web Browser'', then try to bring up a web page.
+
 
+
 
+
* A quick work-around is to disable the internal browser pages in Mylar editors. To do this: ''Window -> Preferences -> Mylar -> Tasks -> Disable Internal Browser''.
+
*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].
+
 
+
 
+
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.
+
# 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> 
+
    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>
+
 
+
:4. Log out and log in again (or type "<code>source .bashrc</code>" at the prompt)
+
:5. Start Eclipse and test the internal web browser
+
 
+
If you are gettig 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]
+
 
+
== Installing on MacOS ==
+
 
+
If you see errors like the following it may be due to Xerces missing from the Mac JDK so you may need to add it to your default classpath.  Please refer to and comment on [https://bugs.eclipse.org/bugs/show_bug.cgi?id=144287 bug 144287] if you see this problem.
+
<code>
+
    Could not create Bugzilla editor input
+
    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.
+
 
+
== Installation FAQ ==
+
 
+
See [[Mylar_FAQ#Installation_Troubleshooting | Installation FAQ]] section of Mylar FAQ.
+
 
+
= 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.
+
 
+
For a visual guide through Mylar please see the online [[http://adobedev.adobe.acrobat.com/p46246963 webinar]]. For additional in-depth information including articles and presentations please see the [[http://www.eclipse.org/mylar/publications.php publications]] page.
+
 
+
= Configuration =
+
After you have installed Mylar, there are a number of things that you can configure to make your experience even richer.
+
 
+
== General configuration ==
+
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.
+
 
+
== Spell Checking ==
+
 
+
Spell checking is supported in the task editor for local tasks and for connectors that support rich editing (e.g. Bugzilla, Trac).
+
* To install spell checking for editors that support it you need to enable the preference in ''General -> Editors -> Text Editors -> Spelling''.
+
* You also need to install a dictionary, some instructions are [http://www.javalobby.org/java/forums/t17453.html here]. A word list is available [[http://wordlist.sourceforge.net/ here]] as well.
+
 
+
[[Image:mylar-spell-checking-preference.gif]]
+
 
+
== Keyboard mappings on Linux ==
+
 
+
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.
+
 
+
If the <code>Ctrl+Alt+Shift+Arrow Up</code> shortcut for ''Mark as Landmark'' does not work do the following:
+
* ''Menu Bar -> Desktop -> Control Centre -> Keyboard Shortcuts -> Move one workspace up, Move one workspace down'': disable both.
+
 
+
If <code>Alt+Click</code> quick unfiltering does not work try one of the following:
+
* Hold down the <code>Windows</code> key while holding <code>Alt</code>, if available (ironic, but unsurprisingly this key is not usually mapped on Linux).
+
* Disable the <code>Alt+drag to move</code> functionality:
+
GNOME Desktop
+
# Open a terminal and run <code>gconf-editor</code>
+
# Go into: <code>/apps/metacity/general</code>
+
# Edit the <code>mouse_button_modifier</code> field. Setting it to nothing disables it. You can use <Super> to set it to the windows key.
+
# Exit <code>gconf-editor</code>.
+
KDE Desktop
+
# Run the ''KDE Control Center''.
+
# Go to the ''Desktop/Window Behavior'' panel and select the ''Window Actions'' tab.
+
# Down in the ''Inner Window, Titlebar & Frame'' area, change the ''Modifier Key'' option from <code>Alt</code> to <code>Meta</code>.
+
 
+
Also, see [[Mylar_Tips_and_Tricks#Keyboard_Shortcuts| keyboard shortcuts]].
+
 
+
= Using Mylar =
+
 
+
One of the most useful things that Mylar can do for you is hide things that you aren't interested in. This allows you to focus on the things you are interested in.
+
 
+
Another high-level thing that Mylar can do for you is help you keep track of tasks.  Mylar doesn't just restrict your view to things that are relevant to you, it restricts your view to elements that are relevant to your current task.  You tell Mylar when you are changing tasks, and it will hide all of the things associated with your current task (window layout and the contents of those windows) and bring up what was on the screen when you left the other task.
+
 
+
Mylar also helps you coordinate tasks among many people, by giving tight integration with bug-tracking (or task-tracking) services.  Mylar doesn't just keep track of tasks that you define, but that other people define as well.  For example, you can work on a specific bug in your Bugzilla repository; the information pertaining to that bug entry is easily available from inside Mylar/Eclipse.  It is very easy to attach a full Mylar context -- what elements are interesting, what windows are open -- to a bug.
+
 
+
== Progress for Categories ==
+
 
+
Categories show progress for the number of completed tasks.  The weekly progress indicates progress in terms of estimated time (by default tasks have an estimate of 1 hour), and the tooltip will indicate progress in terms of both estimated time and number of tasks completed.
+
 
+
[[Image:Progress-categories.gif]]
+
 
+
== Weekly Progress ==
+
 
+
When in ''Focus on Workweek'' mode (right-most toolbar button), the Task List will show a JUnit-style progress bar which indicates how many of the tasks scheduled for the current week have been completed.  Completing a task or deferring to a future week will cause the progress bar to move forward.  The tooltip for the progress bar will indicate the total.
+
 
+
[[Image:Weekly-progress.gif]]
+
 
+
== Incoming Changes ==
+
 
+
All comments added since your last reading of a repository task will be automatically expanded when a task with incoming changes is opened.  Incoming changes are retrieved with the background synchronization to avoid waiting for the server when opening.  Note that a background synchronization is still kicked off upon opening in case changes came in since the last scheduled synchronization.  Repository tasks can be explicitly marked as read or unread.
+
 
+
[[Image:Incoming-changes.gif]]
+
 
+
== Task Repository Integration ==
+
 
+
Task repositories are easy to add, and can be named via the ''Task Repositories'' view.  An icon decoration indicates the repository type.  A task repository can be associated with a project, enabling it to be used for actions such as resolving bug hyperlinks.  '''Note:''' you do not need to associate all of your projects with repositories after updating, since you will be prompted to do this when the associate is needed.
+
 
+
[[Image:Task-repository-integration.gif]]
+
 
+
== Open Task dialog ==
+
 
+
An ''Open Type'' style dialog is available for opening tasks (<code>Ctrl+Shift+F11<c/ode>) and for activating tasks (<code>Ctrl+Shift+F12</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]]
+
 
+
== Repository task attachments ==
+
 
+
Repository task attachments (supported by the Bugzilla and Trac connectors) can be attached via drag-and-drop from both within the Eclipse workspace and from outside, and from text selections, which will invoke the attachment wizard. Attachments can be opened with a browser or corresponding editor.
+
 
+
[[Image:Repository-task-attachments.gif]]
+
 
+
== Task List backup and restore ==
+
 
+
'''Where does Mylar keep the task list?'''
+
 
+
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'').
+
 
+
'''Where does Mylar keep the task list backups?'''
+
 
+
By default, Mylar keeps the task list backups in the <code><workspace>/.mylar/backup</code> folder.
+
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?'''
+
 
+
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.
+
 
+
[[Image:Tasklist-restore.gif]]
+
 
+
'''Can I create manual backups?'''
+
 
+
Yes. Use ''File -> Import/Export ->  Mylar Task Data''. 
+
 
+
[[Image:mylar-tasklist-backup.gif]]
+
 
+
'''Note:'''  uninstalling a connector will cause all of the queries and tasks of that kind to disappear from the Task List, but if you reinstall that connector they will reappear.
+
 
+
'''If the Task List is blank''', either 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.
+
 
+
== Report Bugs from Error Log ==
+
 
+
Bugs can created directly from events in the ''Error Log'' view.  This will create a new repository task editor with the summary and description populated with the error event's details.  If the Connector you are using does not have a rich editor, the event details will be placed into the clipboard so that you can paste them into the web-based editor that will be opened automatically.
+
 
+
[[Image:Report-bugs-error-log.gif]]
+
 
+
== Automatic Duplicate Detection ==
+
 
+
The ''Search for Duplicates'' button on the ''New Repository Task'' editor encourages and facilitates finding similar bug reports before creating a new one.  Potential duplicates are displayed in the Search view which can be used to open a bug and comment or vote if a duplicate is found.  The current duplicate detection mechanism uses stack traces, either automatically inserted by the ''Report as Bug'' mechanism, or manually pasted into the ''Description'' area.  All descriptions and comments of bugs on the corresponding repository are included in the search.
+
 
+
[[Image:Automatic-duplicate-detection.gif]]
+
 
+
== Submitting Contexts ==
+
 
+
When submitting comments, contexts can be attached by selecting the corresponding check-box in the ''Actions'' section.
+
 
+
[[Image:Submitting-contexts.gif]]
+
 
+
== Auto Apply Mylar on Navigator Views ==
+
 
+
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.''
+
 
+
[[Image:Auto-appy-mylar.gif]]
+
 
+
= Team Support =
+
 
+
== Active Change Set management ==
+
 
+
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.
+
 
+
If you are using the '''standard''' mode, ''Change Sets'' toolbar button will only appear if the ''Synchronize'' view is in ''Incoming'' or ''Outgoing'' mode, not in the combined ''Incoming/Outgoing'' mode.  This button must be pressed in order for change sets to appear.  For working with CVS two modes are indistinguishable beyond this limitation.  Subclipse only supports the standard mode.  If you '''switch modes''' you must re-create your synchronization via the ''Synchronize...'' button available from the first toolbar button on the ''Synchronize'' view.
+
 
+
[[Image:mylar-changesets-subclipse.gif]]
+
 
+
If you are using the '''models''' mode, 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]), and until it is resolved '''we recommend that you use the standard mode for CVS'''.  To work around the former, if a Change Set you expect is missing or if you get a "There are no more Incoming/Outgoing changes" message in the view on startup, toggle the third toolbar button between ''All Models'' and ''Change Sets''.  If that doesn't resolve it activate and deactivate the current task.
+
* '''Note:''' if you have enabled the ''models'' mode, but do not see the overlay icon visible in the screenshot below, it is because you are using an old non-models based synchronization.  Old synchronizations are not updated automatically when you switch modes so you must create a new one.
+
 
+
[[Image:mylar-changesets-model-based.gif]]
+
 
+
== Working with Change Sets ==
+
 
+
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.
+
 
+
= Connectors to Repositories =
+
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.
+
 
+
== Bugzilla Connector ==
+
 
+
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]].
+
 
+
== Trac Connector ==
+
The Trac connector offers two access methods:
+
 
+
* '''Trac 0.9 and later''': In this mode the standard Trac web interface is used for repository access. Tickets may be created and edited through a web browser.
+
* '''XML-RPC Plugin''' (Trac trunk): This requires the latest revision (1175) of the [http://trac-hacks.org/wiki/XmlRpcPlugin XmlRpcPlugin] for Trac to be enabled for the accessed repository. The XmlRpcPlugin provides a remote interface to the Trac repository and is distributed separately from Trac (see [http://trac.edgewall.org/ticket/217 #217]). Currently, Trac and the XmlRpcPlugin need to be installed from source. See these [http://trac-hacks.org/wiki/XmlRpcPlugin#Installation install instructions] for requirements and documentation.
+
 
+
The Trac connector integrates Trac queries into the Task List. If you do not know your Trac repository version use the ''Automatic'' setting and click ''Validate Settings''.
+
 
+
 
+
'''New Task Editor'''
+
 
+
A rich editor for creating new Trac tasks is available for repositories that use XML-RPC (see the  [http://wiki.eclipse.org/index.php/Mylar_FAQ FAQ] for XML-RPC configuration instructions).
+
 
+
[[Image:Trac-editor-new.gif]]
+
 
+
 
+
'''Rich Editor, Attachments and Offline support'''
+
 
+
The Trac connector supports the rich task editor.  Attributes and comments can be viewed and edited offline, synchronization is done in the background, and attachments can be posted and retrieved. 
+
 
+
Task Context attachments are supported via the context menu actions in the Task List.  This support requires the Trac XML-RPC plug-in to be enabled and the integration will fall back to the web mode if it is not, (see:  [http://wiki.eclipse.org/index.php/Mylar_FAQ#Trac_Connector_troubleshooting Trac Connector troubleshooting]).
+
 
+
[[Image:Trac-editor.gif]]
+
 
+
== JIRA Connector ==
+
 
+
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].
+
 
+
<b>Rich Editor</b>
+
 
+
The JIRA connector provides a rich editor, offline editing, and change notifications.
+
 
+
[[Image:Jira-editor.gif]]
+
 
+
<b>Search Integration</b>
+
 
+
Searching through JIRA repositories is integrated with the ''Search'' dialog.
+
 
+
[[Image:Jira-search.gif]]
+
 
+
<b>Query</b>
+
 
+
The JIRA query dialog has been streamlined into a single page.  Date range queries are now supported.
+
 
+
[[Image:Jira-query.gif]]
+
 
+
See also [[Mylar_FAQ#JIRA_Connector_troubleshooting|JIRA Connector Troubleshooting]].
+
 
+
==  Generic Web Repository Connector ==
+
 
+
The generic web repository connector is part of the Mylar install.  Refer to the [http://wiki.eclipse.org/index.php/Mylar_FAQ FAQ] for instructions on setting up queries to repositories that are not currently supported by a rich connector (e.g. IssueZilla, GForge, SourceForge, phpBB, VBulletin, Google Code and Mantis).  The parameter list visible below is used for configuring project properties for projects that require them.  These properties are typically derived from the query URL used to access the repository.  Matching rules can be edited under the ''Advanced Configuration'' section on both the ''Repository Settings'' page and the ''Edit Query'' page.
+
 
+
[[Image:Generic-web-repository-settings.gif]]
+
 
+
A generic web-based repository connector allows retrieval of a list of issues from a web page using simple template configuration.
+
 
+
'''For example''', consider the configuration steps for GlassFish project at <code>java.net</code>:
+
 
+
'''1.''' Create new Generic web-based repository. GlassFish is using IssueZilla and has preconfigured template that can be selected by server url ''https://glassfish.dev.java.net/issues''. You can also specify all fields manually in the ''Advanced Configuration'' section. For GlassFish the following settings are required:
+
* Task URL: <code>${serverUrl}/show_bug.cgi?id=</code>
+
* New Task URL: <code>${serverUrl}/enter_bug.cgi?issue_type=DEFECT</code>
+
* Query URL: <code>${serverUrl}/buglist.cgi?component=glassfish&issue_status=NEW&issue_status=STARTED&issue_status=REOPENED&order=Issue+Number</code>
+
* Query Pattern: <code><nowiki><a href="show_bug.cgi\?id\=(.+?)">.+?<span class="summary">(.+?)</span></nowiki></code>
+
 
+
*'''Note:''' ''Query Pattern'' field should have a <code>regexp</code> with 1st matching group on ''Issue ID'' and 2nd on ''Issue Description''.
+
 
+
*'''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.
+
 
+
'''2.''' Create a new query for the GlassFish task repository created above.
+
 
+
*''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.
+
 
+
 
+
'''Templates for the following issue tracking systems are included with the web connector''':
+
 
+
* Google Code Hosting (<code>code.google.com</code>)
+
* IssueZilla (<code>java.net, dev2dev, tigris.org</code>)
+
* GForge (<code>objectweb.org</code>)
+
* SourceForge (<code>sf.net</code>)
+
* Mantis
+
* phpBB
+
* vBulletin
+
 
+
== Rich Task List Client Install ==
+
 
+
Mylar's Task Management features can be used purely as a rich client to supported bug/task/issue trackers. 
+
 
+
For example, to use Mylar as a rich client for Bugzilla:
+
* Install the [http://download.eclipse.org/eclipse/downloads/drops/R-3.2-200606291905/index.php Eclipse 3.2 Platform Runtime] binary (e.g. for [http://download.eclipse.org/eclipse/downloads/drops/R-3.2-200606291905/download.php?dropFile=eclipse-platform-3.2-win32.zip  Windows], [http://download.eclipse.org/eclipse/downloads/drops/R-3.2-200606291905/download.php?dropFile=eclipse-platform-3.2-linux-gtk.tar.gz Linux x86/GTK 2], [http://download.eclipse.org/eclipse/downloads/drops/R-3.2-200606291905/download.php?dropFile=eclipse-platform-3.2-macosx-carbon.tar.gz Mac OSX]).
+
* Use the update site listed on [http://www.eclipse.org/mylar/dl.php Mylar download page] for installing the Task List and Bugzilla Connector.  Note that Mylar requires Java 5.
+
 
+
= Integration with other tools =
+
 
+
'''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.
+

Latest revision as of 11:12, 6 September 2023

The user guide has a new home

Back to the top