We all know that one of the coolest things in Atlassian products are plugins 🙂 With the upcoming addition of the Universal Plugin Manager to Jira, they will become cooler than ever before. Recently, our development team has been looking at improving that even further by making more modules support dynamic reloadability. Our goal is that eventually, we can allow Jira administrators to use all of the awesome UPM features without having to bring down their Jira instance.

The Challenge

When we started planning for the work that needs to be done it quickly turned out that we don’t really know much more about the reloadability of particular plugin modules than our users and plugin developers. Other than ‘educated’ guesses based on our familiarity with the Jira codebase, we didn’t have any reliable, up-to-date source of information of what works and what does not. As true agilists and followers of TDD, we believe that the best documentation you can possibly have about your code is tests. Hence we decided that what we really need to do is to write lots of tests that will tell us which extensions are reloadable already, and which ones are yet to be made so (and why). After deciding on this course of action we faced another challenge: how to test each plugin extension point? Now there are certain plugins that ship by default with Jira. We could use those to write our tests against.

The problem with this approach is that A) some of them cannot be disabled (they are required by Jira to run), so their usefulness for the sort of tests we needed to write is limited B) such a move would tightly couple our test suite to the bundled plugins, that obviously change in a way that is ‘orthogonal’ to the requirements of the tests we were supposed to write. This would readily be a potential source of maintainability problems – each change in bundled plugins (driven by user requirements) might possibly break our tests in unpredictable ways.

The Reference Plugin

So after ruling out that option, we decided to create a Jira reference plugin that would implement all extension points that we intended to test. We implement reference module whenever we move on to testing (and possibly fixing) the next extension point. This way, the reference plugin grows incrementally, together with the testing effort. We try to keep the reference module implementations simple, yet making use of all the features that a given extension supports. Quite often we just shamelessly duplicate ‘real-world’ plugin modules – the goal, in the end, is to simulate real world so that we are able to detect any issues that a real plugin would encounter.

Below you can see how the reference plugin looks in its current state – it already contains more than 20 reference modules.


An Example

Here is an example of a reference workflow validator that hooks into the Jira workflow mechanism via the plugin system and may be configured to allow, or prevent a given workfklow transition.


The Win

As we all know, reference implementation of APIs are very useful things and we already see some great value that the reference plugin brings to the table, beyond being just a nice tool for testing. First of all, it forces us to put on the ‘plugin developer hat’, which is an invaluable experience. So far it has resulted in several bugs and improvement requests raised against the Atlassian Plugins and Gadgets frameworks, as well as improved documentation.

The prominent example is the web items and web section extensions in Jira: as a part of our work we have laid foundations for a comprehensive documentation of all places in Jira that support custom web items and web sections, a sample of which you may see below.


Our Testing

At the moment we keep them internal, but they will soon be available in the public Jira Documentation. In the future, we hope that work on the reference plugin will let us ‘dogfood’ new extension point implementations, provide better APIs and documentation and in general, improve experience of Jira plugin developers, and hence the users as well. For now, we keep the reference plugin internal and run it only in the development and CI environment for our tests. In the future however, we may consider releasing it to the public, to provide live code samples for developers learning how to use the plugin APIs.

This all does not mean that we don’t test on real plugins at all. Our Quality Assurance Engineers have compiled a list of popular Jira plugins and are waiting impatiently for each plugin module story to be completed by the small improvements team. Then they jump in, pick all plugins, whose modules have already been marked as fixed and begin the usual merciless testing excercise. Because this testing happens on the latest trunk builds of Jira 4.3, this has also provided some great value, in that we have been able to discover and fix a change in Jira public API that broke one of the prominent plugins within just a couple of days since introducing that change to the Jira trunk!

To wrap up, making all the important Jira extension points dynamically reloadable is a daunting task that involves big testing effort on our side. On the other hand we can already see how it makes Jira more ‘plugin-friendly’ in ways we have not really predicted while embarking on that mission.

Using a Jira reference plugin to test our plugin s...