Upgrade Managenent

Overview

PluginUpgradeManager is an Upgrade Manager mechanism strongly inspired from JIRA Upgrade Manager. It offers a way to implement an Upgrade Manager dedicated to any JIRA Plugin.

Message to JIRA Administrators

As JIRA administrator, you have to managed JIRA following different ways.

  • The JIRA Configuration are suitable to your activity, then you have only to manage the different projects creation using defaults Schemes. I do no think that it is majority of uses!

  • You or your users prefer to have some specifics configurations concerning Issue Type, Issue Status, Workflows, ... Then, you apply the required/asked configurations using the Administration JIRA Web pages.

    In some company, you may have to reproduce theses configurations on Development, on Qualification and finally on Production environments.

    Here, some of you are looking for any useful Jelly Tags to avoid to apply them manually.
  • You have the knowledge, the capacity and the time to create some new Jelly Tag (not yet provided by Atlassian) in order to simplify the way to apply your configurations. Here, you have a Jelly script able to help you in your configurations. Great !
But, with future release of your settings, will you able to describe in Jelly all required tasks to perform a migration between two release of your settings ?



JIRA UpgradeManager

To apply each required upgrade between different releases of JIRA, Atlassian have developed an Upgrade mechanism the UpgradeManager, in charge of execution a set UpgradeTask.

Each ,UpgradeTask is identified by its own number. You are able to see these number in bottom of JIRA Pages ..
  • (Enterprise Edition, Version: 3.6.5-#161)
  • (Enterprise Edition, Version: 3.7.2-#186)
  • (Enterprise Edition, Version: 3.13.4-#354)
Between the release 3.6.5 and 3.7.2, they are probably 25 UpgradeTask.

Atlassian have defined 3 sets of UpgradeTask around the licence level :

LicenseSet of UpgradeTask
Standardstandardupgrades.xml
Professionalprofessionalupgrades.xml
Enterpriseenterpriseupgrades.xml


Why an UpgradeManager for plugins ?

And so, you may have understand my idea !

I am able to create my own set of UpgradeTask in charge of applying what I want on the JIRA configuration !



Yes, but how may I declared theses UpgradeTask in UpgradeManager ?

Nothing has been done to do that ...



In the first release of my plugins in my company, I have developped a new release of UpgradeManager overriding the JIRA one. Also, I was able to define my own set of UpgradeTask, and they was executed at the restart of JIRA just after JIRA Upgrade.



Since, JIRA 3.3 or 3.4 (I forgot), these solution have been broken due to cyclic dependencies around my own UpgradeManager, the JIRA UpgradeManager, CustomFieldManager, PluginManager and others ...



Now, the implemented UpgradeManager does not override JIRA UpgradeManager.

Description/Features

Minyaa's UpgradeManager is based on :
  • An interface : com.atlassian.jira.upgrade.PluginUpgradeManager
  • An abstract Class : com.atlassian.jira.upgrade.AbstractPluginUpgradeManager
  • A XML file describing the set of com.atlassian.jira.upgrade.UpgradeTask
  • A Jelly Tag : com.atlassian.jira.jelly.tag.ManageUpgrade
Be aware that Minyaa does not provide all features you need to process your upgrade, bu mainly the mechanism to process them.

Developement of these Upgrade Task is under your respponsibility!

Usage

  • Create your(s) UpgradeTask(s)

    You will have to extend the interface UpgradeTask (JIRA native), in order
     public interface UpgradeTask {
         /** @return  The build number that this upgrade is applicable to */
         public String getBuildNumber();
    
         /** A short (less than 50 chars) description of the upgrade action */
         public String getShortDescription();
    
         /** Perform the upgrade. */
         public void doUpgrade() throws Exception;
    
         /** Return any errors that occur.  Each entry is a string. */
         public Collection getErrors();
     }
    
  • Define your Set of UpgradeTask

    You will have to create a XML file (upgrade-jira-plugin-MYPLUGIN.xml) as follow :
    <upgrades type="AddOns"  >
         <upgrade build="1">
             <class>com.mycompany.jira.upgrade.UpgradeTask_Build_1</class>
         </upgrade>
         <upgrade build="2">
             <class>com.mycompany.jira.upgrade.UpgradeTask_Build_2</class>
         </upgrade>
     </upgrades>
  • Create your UpgradeManager

    Each Minyaa Plugin has its UpgradeManager and a UpgradeTask's Set (upgrade-jira-plugin-MYPLUGIN.xml). You will have to extend you own UpgradeManager extending AbstractUpgradeManager and implementing abstracts methods.
          package com.mycompany.jira.upgrade;
          public class YourUpgradeManagerImpl extends AbstractUpgradeManager {
             private static String addOnFileName = "upgrade-jira-plugin-MYPLUGIN.xml";
          	/** Return the fullFileName (Classpath relative) of your Set of UpgradeTask */
          	public String getAddOnFileName() {
          		return addOnFileName;
          	}
    
          	/** Return the Current BuildNumber. */
          	public String getCurrentAddOnBuildNumber() {
          		return "1";
          	}
    
          	/** Return the Required JIRA BuildNumber allow to apply your Set of UpgradeTask. */
          	public String getRequiredJiraBuildNumber() {
          		return "155";
          	}
    
          	/** Return Variable Key used to store the number of your last applied UpgradeTask */
          	public String getKeyParameter() {
          	   return "jira.plugin.version.MyPlugin";		
          	}
          }
    
  • Build your plugin and deploy it in your JIRA.
  • When JIRA is started, go to Adminitration Page on Jelly Runer, and execute the Upgrade as follow :

    <JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraAddOnTagLib">
          	<ManageUpgrade upgradeManagerClass="com.mycompany.jira.upgrade.YourUpgradeManagerImpl" >
          	</ManageUpgrade>
    </JiraJelly>
Now, you are able to define your owns UpgradeTasks and execute them on each of your environment.