Checking Plugins for API Compatibility??

[Leonardo Onieva]

Hello

I'm trying to check compatibility of more than 40 plugins made by my company, compiled for Jira 5.0, to check if they are compatible for 5.2.10

I have tryed many plugins in http://checkup.atlassian.com/ but never can upload full plugin. The upload proccess finish with an error like this:

Oops, an error occured
This exception has been logged with id 6e2jeni84.

From that moment, I refresh the browser and try to go again to http://checkup.atlassian.com but always show same error (with different log id). I have to clear my browser cache to load again the page.

Also, I was looking for some documentation about changes in Jira API, but only found Release Notes, Upgrade Notes and "Preparing for Jira 5.x", but no information about API changes, deprecated or deleted methods..., Why there isn't API changes Release Notes for developers?

Another question, why there aren't all the Javadoc for all versions in https://developer.atlassian.com/static/

Also, I'm a little confused about the compatibility of a plugin. For example, in our case, we have lot of plugins with a pom.xml like this

<properties>

<jira.version>5.0.7</jira.version>

<jira.data.version>${jira.version}</jira.data.version>

<amps.version>3.11</amps.version>

<project.build.sourceEncoding>ISO-8859-1</project.build.sourceEncoding>

</properties>

What exactly does this mean? I can run my plugin in 5.2, but the plugin is compiled with the 5.0.7 API. If my plugin use a deleted method or a method that was changed its number of parameters, how do I know this incompatibility? Should Jira raise an error when installing this plugin?

What about the amps version? Does the version 3.11 belongs to sdk 3.11?

Why doesn't happen anything if I have sdk 3.9 installed in my developer machine?

In summary, which are the best ways to check plugin compatibility?

Thank you

Best regards

[Joe Clark · Accepted solution]

Hi Leonardo,

The https://checkup.atlassian.com site was down today due to some issues with the integration with the Atlassian Marketplace. It should be back up now and ready to accept plugins for compatibility scanning. Please let me know if you have any problems with it.

You've asked a lot of separate questions, so I'm going to quote each one individually and give you a short answer for each. If you'd like more detail on anything, please just let me know.

Also, I was looking for some documentation about changes in Jira API, but only found Release Notes, Upgrade Notes and "Preparing for Jira 5.x", but no information about API changes, deprecated or deleted methods..., Why there isn't API changes Release Notes for developers?

The "Preparing for JIRA x.x" guides should try to list out the most important API changes in each release. There are currently no public documents released detailing every single API method or type change in each release of our products. We appreciate that this is a problem for developers wishing to perform compatibility audits, and it's something I hope we can improve on in the future. The short answer for the reason why this is not done currently is that our products (JIRA and Confluence, mainly) are just so big now and have so many developers working on them that it is actually quite difficult to build a comprehensive list of all changes that would affect developers in each release.

On the positive side, we do now have a published API policy for JIRA, which may provide some guidance for you: https://developer.atlassian.com/display/JIRADEV/Java+API+Policy+for+JIRA

Another question, why there aren't all the Javadoc for all versions in https://developer.atlassian.com/static/

Javadoc on developer.atlassian.com is maintained manually for some products (including JIRA). We are working on automating this for every release. You can see the full javadoc for every version of every product on https://docs.atlassian.com (eg. https://docs.atlassian.com/jira/5.1.8/)

Also, I'm a little confused about the compatibility of a plugin. For example, in our case, we have lot of plugins with a pom.xml like this

<properties>

<jira.version>5.0.7</jira.version>

<jira.data.version>${jira.version}</jira.data.version>

<amps.version>3.11</amps.version>

<project.build.sourceEncoding>ISO-8859-1</project.build.sourceEncoding>

</properties>

What exactly does this mean? I can run my plugin in 5.2, but the plugin is compiled with the 5.0.7 API.

Yes, that is exactly what it means. The <jira.version> controls the version of JIRA that your plugin is compiled against. Generally, it should reflect the lowest version of JIRA that your plugin is compatible with. It also supplies the default version of JIRA that will be used when you use the "atlas-run" command with the Plugin SDK.

If my plugin use a deleted method or a method that was changed its number of parameters, how do I know this incompatibility?

You can change the <jira.version> to the later version of JIRA and do a test compile. Or you can use checkup.atlassian.com, which should report if you are using methods that have changed or are no longer valid.

Should Jira raise an error when installing this plugin?

No, not necessarily. Depending on where the incompatibility is, the code may not execute until certain parts of your plugin are accessed. Just because a plugin installs successfully does not necessarily mean that the plugin is compatible with that version of JIRA.

What about the amps version? Does the version 3.11 belongs to sdk 3.11?

Yes, that is correct.

Why doesn't happen anything if I have sdk 3.9 installed in my developer machine?

If your pom.xml specified version 3.11, but you only have 3.9 installed, then the Plugin SDK should be able to automatically download the required version using Maven. Is this happening for you? If not, what error are you getting?

In summary, which are the best ways to check plugin compatibility?

The best way is to have a comprehensive set of unit tests and acceptance tests that you can run against the plugin using multiple versions of JIRA. Or, alternatively, have a comprehensive manual test plan for your plugin. These are the only ways to be 100% confident with the compatibility of your plugin. All the other solutions, while helpful, don't really provide any guarantees. Even if your plugin compiles, and the checkup.atlassian.com says it is compatible, there is still no way to automatically check for subtle changes in API behaviour that could break your plugin.

[Leonardo Onieva]

Hello Joseph, thank you very much for your answers. I've tryed a plugin in checkup and now it seems it works! I'm going to analyze the results as I can and let you know.

Best regards, Leo

[Timothy]

Still throwing an error for me

[rich]

Would you mind trying to upload your plugin again? We had some issues with checkup that was causing the app to throw 500 errors. Thx.

[Timothy]

It looks like there is an error with that app itself.

To check if your code compiles, change jira.version to 6.0. Do a atlas-clean and atlas-package.

[Leonardo Onieva]

Thank you Timothy for your fast answer.

Ok, but our production version is 5.2.10, are you sure I should change version to 6.0 enstead of 5.2.10?

If my code compiles with 5.2.10 does it means it's 100% compatible? what about deprecated methods?

Do you know if it's dangerous to install in Jira 5.2.10 plugins compiled for older versions?

Regards

[Timothy]

Oh. Sorry. Was all hyper with the 6.0 release.

Depreciated code is still usable. It's only not usable if its gone.

Do you know if it's dangerous to install in Jira 5.2.10 plugins compiled for older versions?

IMHO, just make sure that it compiles with the version that you are targeting. If you have proper unit and functional tests created, then you're better off.