With the recent launch of Bitbucket Server, many plug-in vendors will have to support both Stash and Bitbucket Server for some time until all clients have transitioned to Bitbucket Server. We already mentioned in a recent blog post how hard it is to support both Stash and Bitbucket Server in one plug-in. Therefore, most vendors will have to provide different JAR files for both products for a transition period. Once a customer decides to upgrade its Stash instance to Bitbucket server, all installed plug-ins are automatically deactivated, but should then be able to get upgraded by one click. To make this work, it is important to use semantic versioning right. In this blog post, we will discuss the potential issues and how we can circumvent them.
Atlassian UPM and semantic versioning
The Atlassian Universal Plug-in Installer (UPM) uses semantic versioning to decide if a plug-in is not up-to-date anymore and can thus be upgraded to a more recent version available in the Atlassian Marketplace. As it is well known, semantic version numbers are of the form MAJOR.MINOR.PATCH, where the three parts have the following meaning:
- MAJOR version for incompatible API changes,
- MINOR version for adding functionality in a backwards-compatible manner, and
- PATCH version for backwards-compatible bug fixes.
When you want to provide the same feature set for both Stash and Bitbucket Server, you probably want to use the same version numbers for transparency and traceability reasons. And you also want to have the same Marketplace listing for both the Stash and Bitbucket Server plug-in versions. This means that you cannot use the same version numbers for both products. So you have to add some kind of suffix to your version string to differentiate between the versions for Stash and Bitbucket Server. When talking about version strings, we mean the ones you specify in your atlassian-plugin.xml:
atlassian-plugin.xml snippet with version strings
Where the version number is taken from your POM file by the Atlassian plug-in framework:
Atlassian plug-in pom.xml version snippet
Version suffixes are well known in the Maven universe. The most famous one is probably the “-SNAPSHOT” suffix, but you also sometimes see “-beta, “-m3”, a timestamp like “-20090803125803” or a build number. However, when using a version suffix, we have to keep in mind that UPM will only allow the upgrade of plug-ins when they have a newer version string in terms of semantic versioning. When a user upgrades from Stash to Bitbucket Server, the version string of the plug-in version for Bitbucket Server has to be considered newer than the one of the Stash version in order to make this work.
In practice this means that a version string suffix should be used for Stash and NOT for the Bitbucket server plug-in versions. If we would use a suffix “-bitbucket-server” for all plug-in versions targeted to Bitbucket Server, this would not work because a version string like “1.2.3-bitbucket-server” would be considered less than “1.2.3” because non-numeric qualifiers are considered to be less than final version strings which perfectly makes sense for their normal use case (“-beta”, “-m3”).
We therefore suggest the following naming schema to make plug-in upgrades work:
- Bitbucket Server: MAJOR.MINOR.PATCH (e.g., 1.2.3)
- Stash: MAJOR.MINOR.PATCH-stash (e.g., 1.2.3-stash)
This has the additional benefit that once you decide to only support Bitbucket Server anymore, you will have version numbers without any suffixes.
Also keep your build numbers consistent
Beside the version numbers, the Marketplace also knows the concept of build numbers. The ordering of plug-in versions based on their build number is what determines how UPM offers updates to newer plug-in versions. But note that when attempting the update, the UPM uses semantic versioning instead. Beside following the semantic versioning approach explained above, it is therefore also important to use higher build numbers for your Bitbucket Server plug-ins than for the Stash versions.With that in mind, your users should not experience any issues when upgrading from Stash to Bitbucket Server.