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.
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
|JIRA version||AUI version||AUI components available|
|5.0.0||3.5.5||Dialog, Dropdown, Group+Item, Forms, Icons, Inline-dialog (popup), Messages, Tables, Tabs, Toolbar|
|5.1.x||3.5.5||Dialog, Dropdown, Group+Item, Forms, Icons, Inline-dialog (popup), Messages, Tables, Tabs, Toolbar|
|5.1.8||3.7-m6||Dialog, Dropdown, Dropdown2, Group+Item, Forms, Icons, Inline-dialog (popup), Messages, RESTful Table, Tables, Tabs, Toolbar|
Badges, Dialog, Dropdown, Dropdown2, Group+Item, Forms, Icons, Inline-dialog (popup), Labels, Lozenges, Messages, RESTful Table, Tables, Tabs, Toolbar
Avatars, Badges, Breadcrumbs (Navigation), Buttons, Dialog, Dropdown, Dropdown2, Group+Item, Forms, Icons, Inline-dialog (popup), Labels, Lozenges, Messages, RESTful Table, Tables, Tabs, Toolbar, Toolbar2, Tooltips
Multi-step Progress Tracker, Page Layouts, Page Panel/Content Layouts, Navigation (Horizontal, Vertical)