• This forum has been archived. New threads and replies may not be made. All add-ons/resources that are active should be migrated to the Resource Manager. See this thread for more information.

[Best Practice] Product Version Numbering

Andy Huang

Well-known member
In XenForo, there are two version related strings for add-ons: Version String, and Version ID.
Version String is what is displayed to the general public when your product gets installed, where as Version ID is an internal value. XenForo follows Major.Minor.Revision versioning format and occasionally appended with some additional information. To start apply this to your product, we should look at individual digit in the versioning numbers.

Major: This is changed in your product version when major fundamental changes are implemented. For example, vBulletin went from 2 to 3 when they introduced phrasing system to allow better internationalization, as well as provided substantial rewrite in the original software.

Minor: This is changed in your product version when major new feature are introduced. For example, vBulletin went from 3.0 to 3.5 when the plugin system was introduced, allowing developers to add features to the software without having to modify the source code directly.

Revision: This is changed whenever a maintenance release is pushed out. Most of the time, release under this version change would address bugs in the existing software corrected over period of time. The release frequency of this is depending on individual software needs.

Other values we often see appended are: Alpha, Beta, RC, "Gold" (Stable), and Patch Level.
Alpha: Early development code, coding convention and functions may still be changed around a lot. It is usually not something you'd release to the public. This usually happens before the .0 release.

Beta: Early development code, coding convention and functions are starting to take shape and not being changed as much anymore. Features are mostly implemented and while bugs may still appear frequently, is generally usable, and gives a good understanding as to how the stable version of the software may look like.

RC: Release Candidate, this is when code are mostly all in place, and features are finalized. Code change after this point typically only addresses bugs that have been found and only minor features may be added.

"Gold" (Stable): With exception of the .0.0 Gold initial release, this is often omitted. Gold ("Stable") release is when the developer deems software is stable enough to be used by general public, and should encounter almost no problems. Of course, as more and more people start using the software, obscure bugs may be found, which is why there will be subsequent releases...

Patch Level (PL): Patch Level releases are used only to address serious security related issues. Say for example you have a bug tracker recording all the bugs you've received. You may already have 17 to 20 bugs fixed, but these will not be included in the Patch Level release. Patch Level release will address that 1 major serious security bug that just got reported and fixed.

Now, how should you use Version ID for your product? XenForo Ltd. is using an almost cryptic version ID for the XenForo Product. 1.0.0 Beta 1 is listed as 1000031. Digging into the source code, we understand how they are using it, and why we should follow a similar format:
PHP:
public static $versionId = 1000031; // abbccde = a.b.c d (1: alpha, 3: beta, 5: RC, 7: stable, 9: PL) e
Or, color coded for your fancy:
1000031
Major: 1
Minor: 00 (0)
Revision: 00 (0)
State: 3 (Beta)
State Version: 1

Why should you use this format? It provides a consistent format which is always growing in number, and you can reference the version ID to know exactly which version you are building even if you accidentally remove the Version String.

Why shouldn't you use this format? The only situation where I can see that you shouldn't use this version format is if you intend to go above major version 10... At which point, I don't really know how it would pan out. But realistically that's pretty far down the road and I don't think we'd need to worry about it just yet.

A few examples to get you started:
1.0.0 RC 2: 1000052
1.0.0 Gold: 1000070
1.0.1: 1000170
1.3.1 PL 1: 1030191

Hope this helps!
 
What happens if your Beta / RC etc goes past 9 ? e.g. 1.2.1 Beta 10

(ok, possibly unlikely, but I'll ask anyway).
 
Probably means you'd need to find a better time to declare Beta/RC then ;)
To be honest, I don't know... I probably would have reserved more digits for my personal format (IE: 000.000.000.00.000; 3 digits major, minor, revision, 2 digits for different state -- alpha: 00, beta 20, rc 40, stable 60, pl 80, and 3 digits state version), but I think this is one of those "We can't foresee how IPv4 will be running out later down the road" problem where we only can see it better after it is already put in use :)

One thing I would suggest to do -- if you really run out of numbers -- is to use the extra space digit. Note currently, beta is 3, and rc is 5; if you need more than 9 beta's (odd, but may occur), you can probably make use of the space between 3 and 5 (namely, 4), so 1000040, 1000041, etc. etc. That should give you a good 19 (since we don't really use xyyzz30) beta and RC versions...
 
The likely problem with too many digits is it wouldn't be representable as a 32-bit integer. Also, if your major version is greater than 9, there's no problem if treating it as an int. $major = floor($version / 1000000).
 
For add-ons, all you really need to do is increment the version ID every time you do a release, but if you want to follow our 1000040 system that works too :)
 
Top Bottom