How to do Semver with plugins?

IntelliJ Platform
1

Hi there, I like to use Semantic Versioning for my plugins. I’ve released version 1.3, but there’s a bug in it, so I’d like to release version 1.3.1. While this seems simple, I can’t get this to work. The plugin verifier says:

Invalid plugin descriptor ‘plugin.xml’. The parameter [131] and the plugin version [1.3.1] should have a matching beginning. For example, release version ‘20201’ should match plugin version 2020.1.1

I’d say that these beginnings are matching, but the verifier doesn’t agree with me.

How can I address this (I’ve released a 1.4 for now, but technically, that’s a bit misleading).

Cheers,

Erik

2

The plugin version follows the semVer convention, but the release number is a bit different. At least, this is my observation. I don’t remember how it works exactly and I found nothing in the documentation. It’s like the XXY release should match the XX.Y version (and this is more complicated if you have a XXXXY release). Globally, the release number contains the MAJOR (1) and MINOR without a dot. So, you may want to set the release to 13.1.
Again, this is only my experience, nothing official.

(1) MAJOR and MINOR from the SemVer convention. I’m saying that because IDE versions follow a different convention: YEAR.MAJOR.MINOR, plus an optional patch ^_^. This is important for commercial plugins because the trial period resets for each MAJOR version and, in this case, this applies to the release number, not to the version. In other words, if you publish a 2026.1, then a 2026.2 release, users will get new trials. This is a problem if you publish “major” versions (even if these would be “minor” versions from the SemVer point of view - you see how it’s confusing?) too frequently, but this is another subject.

Edit: one last thing. If your plugin is old (created ~4 years ago), it may follow a different convention.

3

Thanks for sharing! The commercial plugin trial thing is definitely something I wasn’t aware of! I publish 1.4, 1.5, 1.6 almost weekly for my commercial plugins. I’ve been doing this for months now, I had no idea the trial period was even related to this version numbering. This is “unexpected”, to say the least, so thanks for sharing, it seems I’ll have to adjust my numbering.

4

I don’t think I can set the release to 13.1, cause what would be the release version for my real 13.1 release…?

5

I’m using this plugin

id("com.github.jmongard.git-semver-plugin")

to manage semver, mainly use commit message to understand if bump up the version or not.

Mainly with this logic:

  • MAJOR → Breaking Change
  • MINOR → New Feature
  • PATCH → Bugfix or anything else

The convention follow Conventional Commits and I’m pretty happy on how it works.

It’s also able to generate a release notes (but only in MD, I think JetBrains marketplace need it in HTML).

Managing different Intellij releases is kind of complicated, you will need different branches with different suffix for each one, that is kind of troublesome, I personally give up on support different version, I just build for the latest (and all the one compatible with the latest), but is not a commercial plugin.

6 
        version="1.3.1"
        productDescriptor {
            code = "XXXXXXX"
            releaseDate = "########"
            releaseVersion = "13"
            optional = true
        }

ReleaseVersion follows the MAJORMINOR format, MINOR is the last number of the releaseVersion.

In your case: releaseVersion=“13”, release versions like 1.3, 1.3.0, 1.3.1… are all acceptable.

Every time releaseVersion is changed, it means a new subscription is required, and it also means a new trial is available.

7

Hi Vanco,

Sorry, but what? A new subscription is needed? So you mean that releasing a 1.3, 1.4, 1.5 release requires a new licence every time for my users? That doesn’t sound great, I hope I’m misunderstanding this?

Cheers,

Erik

8

Only if you change the releaseVersion string. To avoid this, change the PATCH of the version instead, and do not change the releaseVersion.

Note the difference between releaseVersion and version. In plugin.xml, they correspond to:

<idea-plugin>
   <version>1.3.1</version>
   <!-- paid plugin only -->
    <product-descriptor code="XXXX" release-date="20240728" release-version="13" optional="false" />
</idea-plugin>

DO NOT change anything in product-descriptor if you don’t want a new subscription.

9

AFAIK the release-version defines when an active or new subscription is needed for fallback licenses.
New plugins don’t have the fallback license enabled by default, iirc.

A user with an active subscription can use the plugin with any release-version.

A user with a fallback license for 1.3 (release-version=13) can not use a plugin with release version 1.4 (release-version=14).

Always change the release-date and the release-version at once.

As mentioned before, never change the product code, which identifies the plugin and the license to require.

1 Like
10

Thank you all for the feedback, I was doing this completely wrong. I won’t change the release version anymore, and I’ll only update the “version”.

So I shouldn’t change the release-date either? My assumption was that the release date was the date of the release. It seems I’ve missed some instructions in the docs.

11

I still don’t fully understand the versioning it seems.

I have a current plugin, it’s version 1.2.0, both in the build.gradle.kts, in the plugin.xml, and in the product descriptor:

  <version>1.2.0</version>

  <product-descriptor code="PBEARDEDTHEME" release-date="20260213" release-version="12" optional="true"/>

Now, I’d like to release an update, so I decided not to touch the release-date and the version, and instead just release an 1.3, like this:

  <version>1.3.0</version>

  <product-descriptor code="PBEARDEDTHEME" release-date="20260213" release-version="12" optional="true"/>

Unfortunately, this isn’t allowed:

Invalid plugin descriptor ‘plugin.xml’. The parameter [12] and the plugin version [1.3.0] should have a matching beginning. For example, release version ‘20201’ should match plugin version 2020.1.1

Now, how can I release this 1.3 version without resetting trials/subscriptions etc? Or should I just let go of this 1.3, 1.4 releases, and go for 2026.1.0, 2026.1.1 etc?

thanks, Erik

12

You put in 1.2.0 first, that is release 12 (the versioning is major.minor.patch, so patch was 0 and got removed).

Now you moved to version 1.3.0, which evaluates to 13, but release-version is still 12, so that’s a conflict.

Anytime you touch release-version the free trial gets reset, unconditionally. The only way for you to release a new version without resetting the free trial is if you release 1.2.X, where X is higher than the latest release 1.2.Y version (in your case you need to use 1.2.1 or higher).

I wish this changed. It restricts how well you can represent the significance of a release. I’d do a ton more minor releases, but I rarely change the plugin enough to warrant a new free trial for users.

Especially for someone developing a freemium plugin (my case) - I might change the base free functionality significantly in a way that warrants incrementing the major/minor version - but that would mean resetting the pro free trials (Which had absolutely zero changes), so I have to kind of “break” the versioning scheme to avoid that…

Reference: Do free-trials reset?