For most Jira Server users, an upgrade is a major activity that requires careful planning. What is your upgrade plan? How will you prepare? How will you ensure success? How often will you upgrade?
I approach upgrades as five high level steps:
Step 1: Research
Conduct all pre-upgrade “what changed” and compatibility research
This very important first step can determine the success of your upgrade. Start by reviewing the retrospective from the last upgrade so you can improve the upgrade process and plan for issues encountered in the last event. Also, it’s a good time to make sure your emergency rollback plan is still accurate.
Next, read all of Atlassian’s “Release Notes” and “Upgrade Notes” for every version between yours and the one you’re upgrading too.
TIP
Look for changes that might impact the application, users, or user behavior. Look for bugs you’ve been waiting for fixes for.
Also read the Security Advisories, End of Support announcements, and End of Life policy.
TIP
Ask your REST API and database users to read the Atlassian documentation too, so they can prepare for any changes needed in their applications.
After, verify the compatibility of your hardware, operating system, database, java version, add-ons, and any internally developed customizations. Resources: Jira Requirements, Supported Platforms, and Checking Add-On Compatibility
Finally, double-check that your license is valid through the upgrade testing period and you are not about to reach your license limit. You don’t want license issues to delay your upgrade.
Step 2: Pre-Upgrade Tasks (Test Environment)
Copy all production data to lower environments, update plugins, upgrade and test
RECOMMENDATION
Don’t have a test environment? Remedy that issue first! Ideally you’ll have a secondary server instance but if that’s not possible at least create a local instance on your personal computer. Make sure the resources powering your test environment match your production environment as much as possible. Make sure the software version and configuration are an exact copy of production.
RECOMMENDATION
Before upgrading your test environment, be sure to copy all of your production data to the environment. It’s not enough to test an upgrade on a vanilla instance; you need to test it with your specific configuration data!
By now you should know which version you’re able to upgrade to. Download the installer file, stop the application, and run the binary. Document the installation process, so you can repeat the steps in production. Review all configuration files, paths, custom files, and settings for accuracy. Also check the logs for major problems.
If all is well on startup, it’s time to update the Universal Plugin Manager, other add-ons, and re-index. After the re-index, start your regression testing. Make sure all basic application functions and new features are working as expected.
MISTAKE
During testing, I discovered one of my heavily used plugins wasn’t compatible with the upgrade version and had moved from free to paid. I clicked the “Buy Now” button on the “Manage add-ons” page, assuming it would take me to a shopping cart with pricing information. Instead, it immediately installed an unlicensed version of the new plugin code! All of our workflows broke and I was inundated by reports of license errors from users. I had to quickly generate a free trial code to restore functionality and sheepishly contact the purchasing department to secure emergency funding for the new plugin. I did all this in production! #facepalm
Finally, contact your REST API and database users so they can verify all is well with their applications. Also, compile any “new features” documentation to share with end users. Conduct an end user and project-level admin demo if UI or feature changes are substantial.
Step 3: Upgrade Preparation
Line up support resources, schedule production upgrade activities, and announce plans
At this point, you are confident in the stability of your test environment and ready to schedule the production event. Start by identifying an upgrade team. Who will execute the upgrade? Who will “smoke test” the major functions? Who can you contact if there’s emergency?
After you have your team assembled, pick an upgrade time outside of peak use hours. Communicate the upgrade date, time, and expected duration to users and any support teams, like the company help desk or network operations center. Don’t surprise these teams with “Jira is down!” reports during the upgrade window!
TIP
Use Jira’s announcement banner function to communicate upgrade plans.
Sample Code:
<div style=”border: 1px solid #9e1c1c; background-color: #fff; padding: 10px;”>Upgrade Outage
The upgrade will start on [day], [date] at [time] [timezone] and conclude before the start of business on [day], [date]. During the upgrade window: (1) you WILL NOT be able to login to JIRA, (2) any changes attempted WILL NOT be retained, (3) API calls will fail, and (4) issue creation via email will fail. For a list of new features and fixes, see our JIRA Upgrade notes.
Download sample wording for your entire upgrade process from the Strategy for Jira store.
Step 4: Upgrade Tasks (Production)
Backup production data, update add-ons, upgrade and test
RECOMMENDATION
Hopefully you’re already taking regular (automated) backups of your database and file system. But when’s the last time you verified that your most recent backup occurred and is actually usable? Do that before proceeding.
At last, you’ve planned as much as possible, know what to expect, and are ready for the upgrade event! It’s time to repeat the installation steps you practiced in your test environment including: installation, add-on updates, and regression testing. Use the notes you took in step 2 and be sure to address any differences that exist in the production environment.
Step 5: Communication
Announce upgrade and communicate changes and benefits to user base
Finally, it’s time to announce the upgrade to users and complete post-upgrade steps.
RECOMMENDATION
Use Jira’s announcement banner function to communicate the upgrade is complete. Include a link to the “new features” documentation you compiled in step 2.
Review any previous trouble reports, in case the upgrade remedied them, and be ready to respond to new reports. Check in with your REST API and database users, to make sure all is well with their apps.
Finish any outstanding tasks, compile your retrospective, and make any needed plan updates in preparation for the next upgrade. Also be sure to thank your upgrade team!
Detailed Upgrade Plan
A well-crafted plan can help ensure upgrade success. Download the sample upgrade plan worksheet. Customize it to fit your needs and environment. This worksheet may contain more or fewer steps than necessary for your situation, but it gives you a great starting point. Don’t forget to update and improve the plan after each upgrade.
A test instance and a healthy application are the foundation of a successful upgrade event. You’ll want to upgrade often for the newest features, fixes, and performance improvements. Happy upgrading!