FishEye for JIRA

Name JIRA FishEye Plugin
Vendor Atlassian Pty Ltd (Website)
Authors Atlassian
Homepage http://confluence.atlassian.com/display/JIRAEXT/FishEye+for+JIRA
Issue Management http://developer.atlassian.com/jira/browse/FISH
Categories Remote Access
Version 1.5
Availability JIRA v3.12.2 to v3.12.3
State Stable
Support Atlassian Supported Plugins
License Freeware / Open Source (BSD)
Price Free
Release Docs http://confluence.atlassian.com/display/JIRAEXT/FishEye+for+JIRA
Java API Docs n/a
Download Source http://svn.atlassian.com/svn/public/contrib/jira/jira-fisheye-plugin/tags/jira-fisheye-plugin-1.5
Download JAR jira-fisheye-plugin-1.5.zip
FishEye/Perforce Plugin Beta Released!
The JIRA FishEye/Perforce Plugin has been released in beta! If you're a Perforce user, check it out
Bugs, Feature Requests & Improvements?

If you've found a bug in the JIRA FishEye plugin or would like to request a new feature or improvement - please raise an issue in the JIRA FishEye Plugin project.

Contents

Compatibility With JIRA

Plugin Version 3.6.x 3.7.x 3.8 3.8.1 3.10.2 3.11 3.12.1 Tested Supported
0.8                
1.0              
1.1.2                
1.3         David Chui (Jan/29/2008)  
1.4            
1.5            

Description/Features

The JIRA FishEye Plugin adds a range of FishEye — and optionally Crucible — integration points to your JIRA instance.

The Open Source Hibernate JIRA (hosted by Atlassian) and jira.developer.atlassian.com are both currently running the JIRA FishEye plugin if you're after a working demonstration.

Issue Tab Panels

FishEye & Crucible Issue Tab Panels are added to your JIRA 'View Issue' page. They will only be visible to any user with the 'View Version Control' permission.

The FishEye Issue Tab Panel:

The FishEye Issue Tab Panel will display changesets found in your FishEye instance which reference the JIRA issue key in their commit log message.

  • Collapsible changeset for easy viewing of large or very active repositories.
  • Log message preview mode when changesets are 'collapsed' for easy browsing.
  • All of the standard FishEye links for each revision (diffs, file history, file download, changeset, etc.) in the normal FishEye look-and-feel  - effectively giving you a FishEye view without leaving your JIRA instance!
  • Crucible 'Create Review' links per changeset and for all changesets.
  • Links to any related Crucible reviews
  • Automatic parsing and linking of issue keys within commit messages for quick access to related issues.

The Crucible Issue Tab Panel:

The Crucible Tab Panel displays any reviews associated with source in the FishEye panel.

Project Tab Panels

FishEye & Crucible Project Tab Panels are added to your JIRA 'Browse Project' page. Again, these will be visible to any user with the 'View Version Control' permission.

The FishEye Project Tab Panel

The FishEye Project Tab Panel displays changesets found in your FishEye instance which reference in their commit log message an issue key that belongs to the project you are browsing.

No issue keys?

No problem! Version 1.5 shipped with a feature that allows you to map a project to a particular repository path. Simply navigate to the Project Administration screen of the project you with to map and click Select Path. You can select a path from any of the configured FishEye instances.

  • A configurable Recent Changesets mode that replicates the functionality of the FishEye Issue Tab Panel for all repository changesets across the entire project.
  • An Activity Statistics mode, featuring:
    • A Project Activity chart view showing LOC, Files or Commits for a particular project during the last 7, 30 or 90 days.
    • A configurable Activity per Author pie chart showing each repository author's contribution in terms of LOC, Files or Commits.
    • A configurable Activity per Issue pie chart showing recent LOC, Files or Commits for each particular issue.
  • A FishEye Quick Search box that allows searching of the FishEye repository linked to the JIRA project currently being browsed.

The Crucible Project Tab Panel

The Crucible Project Tab Panel displays the project's issues under review or the reviews with source related to the project.


FishEye Recent Commits Portlet

The FishEye Recent Commits Portlet is available to any user with the 'View Version Control' permission. One or more can be added to a user's dashboard and configured to show a number of recent changesets from a particular FishEye repository branch.

The FishEye Recent Commits Portlet features:

  • Changeset display that replicates the functionality of the FishEye Issue Tab Panel for recent changesets (committed in the last ten days) on the specified repository branch.
  • A FishEye Quick Search box that allows searching of the portlet's configured FishEye repository.
  • A FishEye-style segmented branch URL for quick browsing of your FishEye instance's project hierarchy.

About FishEye & Crucible

FishEye is a repository browsing, monitoring, searching, and analysis tool for CVS, SVN and Perforce.

For more information about FishEye, a list of publicly accessibly live instances and a free 30-day evaluation version, please visit: http://www.atlassian.com/software/fisheye/.

Crucible is a peer code review application that makes it easy to review code changes, make comments and record outcomes in an efficient, distributed, and process-neutral way.

For more information, an online test instance and a free evaluation version, please visit: http://www.atlassian.com/software/crucible/.

Requirements

JIRA Version Plugin Version FishEye Version Crucible Version Notes
3.12.2+ 1.5 1.4.2+ 1.2.2 LATEST RELEASE — All the features listed on this page!
3.12.2+ 1.4 1.4.2+ 1.2.2 No wiki rendering or repository path mapping
3.12+ 1.3 1.4.2+ 1.2.2 No perforce job name -> issue key matching
3.8.1+ 1.1.2 1.2+ n/a Simple crucible integration only (create review icons) and no trusted application support
3.7-3.8 1.0 1.2+ n/a Old-style FishEye Issue Tab Panel & Project Tab Panel. No charts or portlet. No Crucible integration.
3.6.x 0.8 1.1+ n/a Legacy version: Old-style FishEye Issue Tab Panel only. No portlet or project tab panel. No Crucible integration.

For other, obsolete versions - please see this page's attachments.

FishEye Config

Your FishEye instance must have its remote API running — see the Server Settings documentation.

Installing the FishEye plugin

If you're upgrading from an older version of the FishEye plugin, make sure you remove the old plugin JAR file.

Version 1.0+

  1. Remove any older version of jira-fisheye-plugin-x.x.jar from the WEB_INF/lib directory of your JIRA instance.
  2. Download fisheye-jira-plugin-x.x.zip.
  3. Place the fisheye-jira-plugin-x.x.jar contained in the ZIP into the WEB_INF/lib directory of your JIRA instance.
  4. Restart JIRA and navigate to Administration -> FishEye Configuration to configure access to your FishEye instance.

As of version 1.0, you no longer have to restart JIRA after configuration changes to this plugin.

Older versions

Prior to Version 1.0, configuration of the plugin was accomplished via a fisheye-jira-plugin.properties file:

  1. Download fisheye-jira-plugin-x.x.zip and expand it to a temporary folder.
  2. Using a text editor, edit fisheye-jira-plugin.properties and configure to your environment.
  3. Copy fisheye-jira-plugin.properties to the WEB-INF/classes directory of your JIRA instance.
  4. Copy fisheye-jira-plugin-x.x.jar to the WEB-INF/lib directory of your JIRA instance.
  5. Restart JIRA.

Note that you will have to restart JIRA if you wish to update your FishEye configuration whilst using pre-1.0 versions of the plugin.

Other Plugins

Once the plugin is installed and running you might like to uninstall the Subversion Plugin and/or disassociate CVS modules from your projects so as to disable JIRA's periodic CVS indexing.

Upgrading the FishEye plugin

In all cases, you will need to remove the previous plugin jar first.

If you are upgrading from 1.1 or below to 1.4, there is a bug which will cause any previously configured Recent Commits portlets to not display correctly. There is a quick fix available, and the problem has been solved for the next release.

If upgrading from 1.0+ to a higher version:

Sit back and relax! All FishEye configuration data is backwards compatible and persisted to the database. If you've previously configured your FishEye plugin using the FishEye Configuration screen, all you need to do is drop the plugin jar into your WEB-INF/lib directory as per the installation instructions above.

If upgrading from a pre-1.0 version to version 1.0 or above:

Version 1.0+ will read through to the properties file you have previously configured for your JIRA instance, however for easier configuration and upgrading in the future, we recommend that you delete your existing fisheye-jira-plugin.properties file and instead configure your connection via the FishEye Configuration administration screen.

Reading through to the properties file is deprecated and will be removed in a future version of the plugin.

If upgrading from a pre-1.0 version to another pre-1.0 version:

Follow the steps for Installing as above, but before starting:

  1. Take a copy of your existing settings at JIRA_HOME/WEB_INF/classes/fisheye-jira-plugin.properties
  2. Delete JIRA_HOME/WEB_INF/fisheye-jira-plugin*.*

Using the FishEye plugin

When JIRA asks FishEye for information, it identifies itself as a particular user. There are three ways that you can configure authentication for the FishEye plugin:

  1. Do not set up any authentication in JIRA — you may not wish to set up authentication between FishEye and JIRA, if you are running a public instance of FishEye. This is obviously the least secure method of using the FishEye plugin.
  2. Set a username/password on the 'FishEye Configuration' page in JIRA — all requests will be performed as the user entered into the 'FishEye Configuration' page, no matter who is actually logged into JIRA.
  3. Configure Fisheye to trust JIRA and leave the username and password blank on the 'FishEye Configuration' page in JIRA — all requests will be performed as the user who is currently logged in to JIRA. Note, this means that your JIRA users must exist in FishEye as well. This is the most secure method of using the FishEye plugin.

The different FishEye integration views are available to any user with the JIRA View Version Control permission. Note that changesets and chart data will be presented for all issues in a particular project, even if the user does not have the relevant permission to view that issue. Issue data (beyond commit log data) will still be secured in the usual way.

The FishEye Issue Tab Panel and Project Tab Panel (including the charts in 'statistics' mode) will only display information related to changesets with a valid JIRA issue key in their log message.

The FishEye Recent Changesets Portlet will display the latest n changesets for a particular repository branch, regardless of commit message.

Performance Tweaks

To improve performance, please consider:

  • Specifying the repositories to search for each JIRA project (in the Repository List section of the FishEye Configuration page).
  • Specifying some performance-related Optional Parameters on the FishEye Configuration page:
    • Limiting the age of project changesets to search for.
    • Limiting the number of changesets per project and changesets per issue to display.
    • Limiting the number of revisions to retrieve for each changeset if there are likely to be large changesets in your repository.
    • Enlarging the revision cache size (the default value is 5000, which should be safe for normal JIRA instances — however, this is highly dependent on current memory usage, total allocated memory, etc. Please reduce this cache size if JIRA starts running out of memory as a result of this plugin being installed).

Troubleshooting

If the plugin tab is not visible on the 'View Issue' or 'Browse Project' page in JIRA, check that:

  1. JIRA reports the plugin as installed correctly on the Administration->Plugins page.
  2. JIRA users have the 'View Version Control' permission.

To enable debug logging for the plugin, edit the file JIRA_HOME/atlassian-jira/WEB-INF/classes/log4j.properties and add the following line:

log4j.category.com.atlassian.jira.ext.fisheye = DEBUG, filelog

Upon JIRA restart the plugin will log copious amounts of debug, including configuration details and FishEye API calls.

If you are still stuck or think you've encountered a bug, please raise an issue in the JIRA FishEye Plugin project.

Version History

Version 1.5 (23/4/2008)

Atlassian Developer Network JIRA (27 issues)
T Key Summary Status
Task FISH-130 The bundled JIRA FishEye Plugin jar not removed during functional test execution. Resolved
Task FISH-85 Update FishEyeProperties to use new JiraPropertySetManager Resolved
Task FISH-148 Functional Testing for Multiple FishEye Instances Resolved
New Feature FISH-114 Render commits as wiki text Resolved
New Feature FISH-153 Option to display ALL commits in a repository branch on Project Tab Panels - not just those with issue keys Resolved
New Feature FISH-154 Fisheye and Fisheye plugin should better handle rescans after update of non-versioned property Resolved
Improvement FISH-61 Make error messages human friendly - instead of printing exceptions Resolved
Improvement FISH-146 Multiple instance support for Recent Commits portlet Resolved
Improvement FISH-149 JIRA accessKey support for config screens Resolved
Improvement FISH-66 Improve documentation/validation on the FishEye portlet config screen Resolved
Improvement FISH-115 Display changes/revisions that do not reference a JIRA issue or project key. Resolved
Bug FISH-132 'Create Crucible reviews for all x issues' link on issue tab panel always points to default FishEye instance Resolved
Bug FISH-120 IllegalArgumentException when cache size is zero Resolved
Bug FISH-140 Crucible tab doesn't display for "project" review keys (e.g. CR-FE-808) Resolved
Bug FISH-136 Repository links on Repository Mapping config screen always use default FishEye instance as baseurl Resolved
Bug FISH-137 Links point to wrong FishEye instance Resolved
Bug FISH-131 The plugin does not flush (clear) valid authentication token when user changes username/password in FishEye Configuration Screen in JIRA Resolved
Bug FISH-22 Plug In Does Not Get Past Stopped Repository Resolved
Bug FISH-129 If one of multiple configured FishEye repositories stops, errors occur on all FishEye project tab panels Resolved
Bug FISH-142 Repository Mapping screen displays repositories are inaccessible to the specified FE/CRU user. Resolved
Bug FISH-145 Better upgrade path for Recent Commits Portlet Resolved
Bug FISH-151 Crucible tab panels only display if Primary instance has crucible configured Resolved
Bug FISH-150 Better display of changes to binary files Resolved
Bug FISH-152 Annoying WARN log messages Resolved
Bug FISH-121 Plugin shouldn't require setup when applinks present Resolved
Bug FISH-127 Fisheye url not resolved when plugin used with Applinks Resolved
Bug FISH-155 plugin version is inconsistent with filename Closed

Version 1.4 (29/1/2008)

Atlassian Developer Network JIRA (1 issues)
T Key Summary Status
New Feature FISH-57 Include support for issue keys referenced in P4 job name / job info Resolved

Version 1.3 (16/1/2008)

Atlassian Developer Network JIRA (17 issues)
T Key Summary Status
Task FISH-53 Supported Plugin Checklist: Setup Bamboo CI build Resolved
Task FISH-87 Design "Try FishEye" screen to be included in bundled FE plugin. Resolved
New Feature FISH-119 Support Trusted Applications Authentication Resolved
New Feature FISH-102 Issues under review statistics charting Resolved
New Feature FISH-106 Crucible project tab panel Resolved
New Feature FISH-48 Add FishEye-style "days/mins/hours ago" next to changeset date Resolved
New Feature FISH-104 Crucible reviews issue tab panel Resolved
New Feature FISH-101 Create review for all issue-related changesets Resolved
Improvement FISH-103 Hyperlink crucible review keys in changeset/review text Resolved
Improvement FISH-27 Allow multiple Fisheye instances from one unique Jira Resolved
Improvement FISH-110 Set finite defaults for "Max Changesets / Issue" and "Max Revisions / Changeset" Resolved
Improvement FISH-105 Display changeset/revision review information in-line Resolved
Improvement FISH-92 Retrieve configuration from the AppLinks Plugin Resolved
Bug FISH-116 Erroneous logging info on FishEyeConfigImpl at initial startup Resolved
Bug FISH-122 Sorting big lists of changes not quite right Resolved
Bug FISH-112 Plugin is not combining results from different repositories Resolved
Bug FISH-33 Respect JIRA's date & time formats Resolved

Version 1.1.2 (15/10/2007)

Atlassian Developer Network JIRA (21 issues)
T Key Summary Status
Task FISH-76 JIRA FishEye Plugin -> Maven2 Resolved
Task FISH-86 Update plugin homepage with anti-aliased screenshots Resolved
Task FISH-77 Plugin functional tests should create their own FishEye instance Resolved
Task FISH-96 "What is FishEye?" blurb in place of View FishEye Configuration page if plugin not configured Resolved
New Feature FISH-79 FishEye dashboard portlet Resolved
Improvement FISH-46 Dynamically resolve list of repositories for a FishEye instance Resolved
Improvement FISH-83 Make config page validation test connection to FishEye instance before updating Resolved
Improvement FISH-84 Revamp Configuration Screen Resolved
Improvement FISH-67 Improve documentation on FishEye Config screen Resolved
Improvement FISH-88 FishEye Issue/Project Tab Panels should be hidden if plugin not configured Resolved
Improvement FISH-95 Project keys in Repository Mappings section of admin screen should be hyperlinked Resolved
Improvement FISH-94 Should display message on project tab panel if there are no commits to display / chart Resolved
Improvement FISH-52 Supported Plugin Checklist: Full i18n of plugin Resolved
Bug FISH-72 Shouldn't output plain text password to logs Resolved
Bug FISH-71 FishEye Config screen: Should have the update button first and then the cancel button. Resolved
Bug FISH-74 actions == null when trying to show FishEye tab Resolved
Bug FISH-45 Respect JIRA Permissions Resolved
Bug FISH-82 "java.io.IOException: anon access forbidden" in plugin when FishEye is restarted Resolved
Bug FISH-90 Limit in number of repositories Resolved
Bug FISH-99 Project tab panel collates statistics for all mentioned issue keys - not just the current project Resolved
Bug FISH-100 Open link in new window broken - always opens in new window Resolved

Version 1.1.1 (2/9/2007)

Atlassian Developer Network JIRA (8 issues)
T Key Summary Status
Task FISH-63 Deprecate old properties file in favour of db properties Resolved
Task FISH-65 Update "Cenqua" references in code, comments, licensing, etc. Resolved