This page last changed on Oct 05, 2009 by alui.

On this page:

Upgrading from JIRA 3.13.x to 4.0

JIRA 4.0 introduces some significant licensing changes. Before you begin the upgrade, please go to my.atlassian.com for your upgraded license. Please note, any existing 3.x license files will not work with 4.0.

JIRA has moved to a user-based licensing model in JIRA 4.0. This means that you will need to calculate the number of users in your JIRA system to determine what license you will need, before you can complete your upgrade. For more information on this, please see the JIRA pricing changes FAQ.

Once you have upgraded your license, please follow the JIRA general upgrade instructions, plus note the following:

Scheduling the Upgrade

Please note that upgrading to JIRA 4.0 may take a long time, depending on the size of your instance as well as server and database performance. During the upgrade, several upgrade tasks will need to run to upgrade your data to be ready for JIRA 4.0, such as:

  • Calculating a resolution date for all resolved issues in your system
  • Re-indexing your issues
  • Converting saved filters to use JQL
  • Converting existing portlets to gadgets

Please schedule sufficient downtime time for the upgrade in your production environment. It is recommended to run an upgrade first in a test environment to see how long the upgrade will take for your data set and hardware configuration.

Java Version

If you are running JIRA under version 6 (1.6) of the Sun JRE, please ensure that you are running a point release JRE 6 (1.6) Update 10 or higher. The reasons for this are:

  • JIRA 4.0 introduces a new REST plugin type based on Jersey, which will not work with JRE 6 - JRE 6 Update 3. If you are running JIRA with one of these versions of the JRE you will see the following errors:
    java.lang.LinkageError: JAXB 2.0 API is being loaded from the bootstrap classloader,
    but this RI (from bundle://16.0:3/com/sun/xml/bind/v2/model/impl/ModelBuilder.class)
    needs 2.1 API. Use the endorsed directory mechanism to place jaxb-api.jar in the bootstrap
    classloader. (See http://java.sun.com/j2se/1.5.0/docs/guide/standards/)
    
    Note: JRE 5 (1.5) doesn't have this problem since it doesn't bundle JAXB.
  • JIRA 4.0 uses Lucene v2.3, which is affected by a Sun hotspot compiler bug in JRE 6 (1.6) Update 4 and upwards (see JRA-15681). The bug is fixed in JRE 6 (1.6) Update10.

JIRA Home

JIRA 4.0 has a new directory structure — for details, please see Important Directories and Files.

Please ensure that you set the jira.home property as described here.

Recommended Browsers

The following browsers are recommended for use with JIRA 4:

  • Internet Explorer 7 and 8
  • Firefox 3.x
  • Safari 4

Users May Encounter 'Advanced Search'

If any of your users have saved invalid filters, the new 'Advanced Search' screen may appear when they try to display them.

'mail.mime.decodeparameters' System Property

The following system property must be set in order for the JIRA mail handler to work correctly with emails from RFC 2231-compliant mail clients:

mail.mime.decodeparameters=true

System properties are set in different ways depending on your application server.

'Resolution Date' System Field

JIRA 4.0 introduces a new system field, the Resolution Date. This field provides the date when an issue last entered into a 'Resolved' workflow state. When upgrading to JIRA 4.0, an upgrade task will run, calculating the Resolution Date for every resolved issue in your system. If you have a large number of issues, this may take a long time. The speed at which this upgrade task runs can be improved by ensuring that your database statistics are up to date for your changegroup and changeitem tables (to ensure the database will select the most effective query plan).

For example, on Postgres this can be done by executing the following commands:

jiratest=# ANALYZE changegroup;
ANALYZE
jiratest=# ANALYZE changeitem;
ANALYZE

JIRA's RPC interface now provides two new methods to retrieve an issue's Resolution Date:

The RemoteIssue class was left unchanged, to ensure backwards compatibility of RPC clients.

Database Schema Changes

If you are using an Oracle or MySQL database, please note that two column data types have been changed.

Therefore, the easiest way to upgrade to JIRA 4.0 is to perform anXML backup and restoreas described in theUpgrading JIRAinstructions.

If in the past, instead of performing an XML backup and restore, you have been upgrading by "pointing" the new version of JIRA at an old database, this is still possible. However, the procedure is more complicated. You will need to use SQL scripts to perform database schema changes.

For details (and the scripts), please see JIRA 4.0 Database Schema Changes for MySQL and Oracle .

Charting Plugin

JIRA 4.0 now bundles most of the charts previously provided by the JIRA charting plugin. If you currently have the JIRA charting plugin installed (v1.4.1 or previous) in  WEB-INF/lib, please remove it as otherwise JIRA will fail to start.

The following three charts have not been bundled with JIRA 4.0. If you are using any of the following three charts, you will need to upgrade to version 1.5 of the JIRA charting plugin:

  • Time to First Response Chart
  • Average Number of Times in Status Chart
  • Average Time in Status Chart

JIRA Toolkit

If you are using the JIRA Toolkit, you will need to upgrade it to the latest version.

You will also need to install it in your JIRA home directory, rather than your atlassian-jira/WEB-INF/lib/ directory as it now runs in an OSGi container. Read Managing JIRA's Plugins for more information.

GreenHopper Plugin

GreenHopper for JIRA 4.0 is now available for use with JIRA 4.0. You can download it on the GreenHopper Plugin for JIRA Downloads page. Please follow the GreenHopper Installation and Upgrade Guide for instructions on how to upgrade GreenHopper.

Please note, you need to upgrade your GreenHopper license before you can use GreenHopper with JIRA 4.0. Any existing GreenHopper license files will not work with JIRA 4.0. You can obtain a license from http://my.atlassian.com.

Issue 'Status' Field Problem

If you have defined two issue statuses with the same name, JIRA's search will not recognise any issues assigned these statuses as distinct issues. For example, consider this scenario:

  1. You have defined two issue statuses in a project, both with the name 'In Progress (Services)', to use in different workflows.
  2. At a point in time, 100 issues are assigned the first status of 'In Progress (Services)' and 50 issues are assigned the second status of 'In Progress (Services)'.
  3. You browse the project's issues. The 'Status Summary' will incorrectly show only one 'In Progress (Services)' status with either 100 or 50 issues (picked randomly). The issue totals in the other summaries (By Priority, etc) will also be incorrect, due to JIRA not recognising the statuses as distinct.

To resolve this issue, we recommend that you ensure that each issue status is distinct by renaming the duplicate statuses appropriately. You may also need to update any issue filters that you have set up.

Plugin Notes

JIRA 4.0 introduces several changes that may break existing plugins.

There are now two different types of plugins. Each type of plugin needs to be installed into a different directory to work. Read Managing JIRA's Plugins for more information.

If you are using a plugin that is not shipped with JIRA, the plugin may need to be updated to work with JIRA 4.0. If the plugin was written by you, please read through Updating JIRA Plugins for JIRA 4.0 and see if any of it is relevant to your plugin. If you are using a plugin written by a third party, please check with the plugin's author to see if the plugin has been tested with JIRA 4.0.

Memory

Running JIRA v4.0 may require more RAM than running v3.x.
The default settings (suitable for small to medium usage) for standalone allocates a total of 512MB memory to the JIRA application.
Please ensure your server has enough available RAM to cover this.
If you are installing JIRA as a WAR/EAR, then you may need to increase the amount of "PermGen" memory allocated to JIRA. 256MB PermGen is recommended.

Upgrading from JIRA 3.12 and earlier

In addition to the points listed above, please read the Upgrade Guide for every version you are skipping during the upgrade. The complete list of Upgrade Guides is available here.

Document generated by Confluence on Oct 06, 2009 00:26