How does Xenforo addon versioning really work?

The XF addon versioning is a bit messy, but makes sense when you get used to it.

You can play around with the widget below to get better familiarized with how it works. (It is a JavaScript-port of the XF Core PHP function)

What should the version_string be set to?

If you use the correct format when bumping the version of your addon, the version_string will be set to the correct value automagically

In other words, it is best to just let the php cmd.php xf-addon:bump-version command handle the logic, and you should not manually edit the version_string-value in the addon.json-file.

Note: If the CLI asks you to "Enter a version string." you have entered an non-standard XF version_id.
Tip: If you put the version too high by mistake, you can rerun the command with the --force flag to enter a new lower version.

How to upload a resource

When uploading the resource and posting a release about the new version, you should do as follows:

Image of the XF Resource upload dialogue
(The version_string-value can be found from the addon.json-file)
Tip: copy & paste the value so there is no risk for a typo...

Playground

Enter a version_id number below to see the correct version_string that will be outputted to the addon.json file (and which you should use as New version number when releasing a new version in XF pages.)

1.0.0

Extra notes on addon versioning

There are 2 undocumented "features" of the XF version_id format..

even states
In-between the version states (1, 3, 5, 7, 9) there are hidden ones (2, 4, 6, 8) that add 10 to the "state version".
e.g. 1020324 is equivalent to 1.2.3 Alpha 14
90-prefix
You can "bump down" version numbers up to 4 times with the 90-prefix. This means that the version_id will be higher than previous version, but the version_string can be "reset" to a lower value. Example:
8040670 is 8.4.6, which is an older version than
901000070 which is 1.0.0
(You should probably use this sparingly and only when really needed)