Building UI for a plugin shipping to multiple versions of JIRA

Before you begin

Please refer to the following documents, which should answer some of your questions:

• Atlassian Design Guidelines (ADG) - the big picture
• Preparing for JIRA 6.0 - general JIRA 6.0 + ADG information
• JIRA Agile ADG Migration Guidelines - a case study on shipping to multiple versions of JIRA. Note, JIRA Agile was previously named Bonfire.

Some suggestions

• Use AUI components exclusively

  The markup patterns for AUI components for most things are practically identical between JIRA 5.x and JIRA 6.0. There should be a minimum of fuss for these things.

• Don't extend or override AUI patterns

  Extending or overriding AUI/JIRA's UI patterns are the #1 reason a UI "breaks" across versions of JIRA.

• Minimise your dependencies

  If you're shipping bespoke UI, it's best to depend on as little as possible - ideally nothing other than your own plugin's assets. If you need something "like this, but a bit different," build it entirely yourself within your plugin. Don't depend on JIRA's or AUI's UI assets whatsoever. If you own the code that renders your UI, the chances of your UI breaking when you deploy it are greatly minimised.

• Put your markup in small, composable templates

  If your markup is static, it will be difficult for you to update your plugin. Instead, pull as many UI concepts as you can out into templates and make template calls. This affords you the ability to swap out templates based on the version of JIRA you're using.

On determining what is safe to rely upon

When building across multiple versions of anything (of which JIRA is a subset), you need to determine your lowest common version for each dependency. Once you know this, you can determine the set of (UI) assets that will be available across all the versions you intend to support.

AUI assets across JIRA versions