Plugin Versioning numbers

PeterT · Today, 10:35 AM

With the recent community involvement in releasing plugin versions to work around calibre changes in cases where the plugin maintainer is either absent from the forum, or the plugin has been abandoned, I've observed some version number conflicts.

Either an invalid version number (ie 1.2.3.4) as opposed to the calibre three part number (1.2.3), a reuse of the officially released plugins version number, or the use of a version number that the developer had intended for their next build but never publically announced on MobileRead.

Any thoughts on standards / techniques that could be implemented to handle these issues?

theducks · Today, 11:21 AM

Does the last character of the 3 part have to be a number?
RE: Caliber does not notify on a last number change.
When alternate (temporary) maintainers step up and base tweaks upon the last release, just add or bump by including a letter. 1.2.3b
That way if 1.2.4 ever gets released... we also know it is from the official maintainer.

JimmXinu · Today, 12:20 PM

All three are integers in code and, as I recall, adding letters will break comparison types when checking which is newer.

My approach is to increment the middle (minor) number for regular releases and to increment the right most (micro or patch) number for test versions or emergency bug fix releases. Community posted versions could also bump micro.

I should have bumped the ME/QC/GrS micro version by 2, or bumped the minor version; I honestly didn't think about it until after I'd already released ME.

FYI, semi-related, Github releases want Semantic Versioning (https://semver.org/) these days. Which does allow for extra specificity after the micro number, but doesn't want anything before the version number. To the point that I've found I have to use "Name 1.2.3" when naming releases because using "Name v1.2.3" can cause github to list releases out of order.

And I do acknowledge that I put out FFF test versions more frequently than most plugins, and that using the micro number for that violates Semantic Versioning rules. We work with what we have.

PeterT · Today, 01:27 PM

Hmmm... maybe adding a 4th number for a beta version will work.

I just hacked an installed plugin on my system to be (1,14,3,1) and tried the plugin update in calibre. It correctly showed that version 1.14.3.1 was installed and that 1.14.4 was available.

Changing the version to (1,14,4,1) shows that 1.14.4.1 is installed with no updates available, and that 1.14.4 is the available version.

So I get the feeling that the simplest solutuon is for community members to leave the first three digits beinbg the version of the plugin they are basing their mod on, add that 4th digit, and to increase it if they do make additional changes.

JimmXinu · Today, 02:23 PM

Perhaps 4 number version is more practical than I assumed.

I'd also like to know what happens if someone does post a 4 number version plugin in a first post--it would likely happen at some point. I'm not sure anyone but Kovid has visibility into the server-side plugin system.

un_pogaz · Today, 02:28 PM

My norm is: Release, Major, Minor, Experimental.
(with Experimental is optional)

Note that the use of the fourth number must be reserved for private use, sharing a test version to the user, and so in the mind of a scope very limited in time. Any official version need to limite itself to the standard three number version.
Incidentally, I like to increase my experimental versions by 100, so 1.2.5.100, 1.2.5.200... the advantage of this naming convention is that it clearly indicates that it is an experimental version, so it easy to catch into the log. Other advantage to put the experimental version into a fourth number is that when a official version is releasead, even with a minor/hotfix change, the official will naturaly overwrite the experimental one on the user side.

In the goal of the initial question of the thread: the maintainer need to use the three version number.
That avoid to confuse the random user that probaly don't know that the plugin has changed of lead developer, and if the original developer ever comes back, he simple have to catch up the version relesead during their absence.

DrChiper · Today, 02:34 PM

So I am to understand that a developer/maintainer must use 1.14.3.0 on an officially release, and is the 1.14.3.1 etc. just for the community?

PeterT · Today, 02:49 PM

Looks as if the cached Plugin index is created by setup/plugins_mirror.py and this code seems to work fine with a 4 digit version number in the plugin.

theducks · Today, 02:50 PM

Quote:

Originally Posted by DrChiper

So I am to understand that a developer/maintainer must use 1.14.3.0 on an officially release, and is the 1.14.3.1 etc. just for the community?

I think the .0 is implied and need not be used for the official release.

un_pogaz · Today, 02:53 PM

@DrChiper Yes, kind of. The fourth number is a placeholder, so the community can use it to share mod or hacky version. Even the dev can use it for test version, check that I fix realy work before deploy it. But I realy insite that any experimental version need to have a very short life time, it can be usefull to share and test a fix version, but at some point, someone need to make a official release as maintainer. The "last working version" cannot be a experimental one you need to found and manualy download at the end of the thread.

DrChiper · Today, 02:55 PM

Quote:

Originally Posted by theducks

I think the .0 is implied and need not be used for the official release.

Ok, so putting a zero (or nothing) on the 4th position will not break the system?

DrChiper · Today, 03:01 PM

Quote:

Originally Posted by un_pogaz

But I realy insite that any experimental version need to have a very short life time, it can be usefull to share and test a fix version, but at some point, someone need to make a official release as maintainer.

Agreed. Just for quick patching purposes to fix a serious problem (=showstopper).

Quote:

Originally Posted by un_pogaz

The "last working version" cannot be a experimental one you need to found and manualy download at the end of the thread.

Agreed.

un_pogaz · Today, 03:07 PM

Quote:

Originally Posted by DrChiper

Ok, so putting a zero (or nothing) on the 4th position will not break the system?

Absolutly not. The way that Calibre (and Python) compare the tuple for version number make that we can compare version with different lenght without issue. It compare one-by-one each pair inside each versions, if a pair is identical, Calibre compare the next pair, else stop comparing at the first different pair.
And if at the end, all the three first pairs are identical, and that one version has a fourth number, the four length "win" de facto.

DrChiper · Today, 03:15 PM

Quote:

Originally Posted by un_pogaz

Absolutly not. The way that Calibre (and Python) compare the tuple for version number make that we can compare version with different lenght without issue. It compare one-by-one each pair inside each versions, if a pair is identical, Calibre compare the next pair, else stop comparing at the first different pair.
And if at the end, all the three first pairs are identical, and that one version has a fourth number, the four length "win" de facto.

That is good to know for us mortals

DrChiper · Today, 03:25 PM

Quote:

Originally Posted by un_pogaz

My norm is: Release, Major, Minor, Experimental.
(with Experimental is optional)

As "Release/Major/Minor" is pretty vague, I would suggest:

Feature Release, Feature Enhancement, Feature Fix, Experimental

This will help on determination when some value needs to be bumped-up.

Today, 10:35 AM	#1
PeterT Grand Sorcerer Posts: 13,643 Karma: 79983758 Join Date: Nov 2007 Location: Toronto Device: Libra H2O, Libra Colour	Plugin Versioning numbers With the recent community involvement in releasing plugin versions to work around calibre changes in cases where the plugin maintainer is either absent from the forum, or the plugin has been abandoned, I've observed some version number conflicts. Either an invalid version number (ie 1.2.3.4) as opposed to the calibre three part number (1.2.3), a reuse of the officially released plugins version number, or the use of a version number that the developer had intended for their next build but never publically announced on MobileRead. Any thoughts on standards / techniques that could be implemented to handle these issues?

Today, 02:53 PM	#10
un_pogaz Chalut o/ Posts: 466 Karma: 678910 Join Date: Dec 2017 Device: Kobo	@DrChiper Yes, kind of. The fourth number is a placeholder, so the community can use it to share mod or hacky version. Even the dev can use it for test version, check that I fix realy work before deploy it. But I realy insite that any experimental version need to have a very short life time, it can be usefull to share and test a fix version, but at some point, someone need to make a official release as maintainer. The "last working version" cannot be a experimental one you need to found and manualy download at the end of the thread. Last edited by un_pogaz; Today at 02:57 PM.

Similar Threads
Thread	Thread Starter	Forum	Replies	Last Post
Pagelist plugin for print edition page numbers	Doitsu	Plugins	38	05-21-2022 03:07 PM
Using GitHub as Repository versioning EPUB	TvdTogt	Sigil	2	07-27-2021 11:57 AM
Page numbers in Evernote plugin	zslengyel	KOReader	0	08-23-2020 01:01 PM
A File Versioning Plugin for Open/Libre Office	Steven Lake	Writers' Corner	0	01-11-2012 12:19 PM

Today, 11:21 AM	#2
theducks Well trained by Cats Posts: 31,204 Karma: 60406678 Join Date: Aug 2009 Location: The Central Coast of California Device: Kobo Libra2,Kobo Aura2v1, K4NT(Fixed: New Bat.), Galaxy Tab A	Does the last character of the 3 part have to be a number? RE: Caliber does not notify on a last number change. When alternate (temporary) maintainers step up and base tweaks upon the last release, just add or bump by including a letter. 1.2.3b That way if 1.2.4 ever gets released... we also know it is from the official maintainer.

Today, 12:20 PM	#3
JimmXinu Plugin Developer Posts: 7,083 Karma: 4604637 Join Date: Dec 2011 Location: Midwest USA Device: Kobo Clara Colour running KOReader	All three are integers in code and, as I recall, adding letters will break comparison types when checking which is newer. My approach is to increment the middle (minor) number for regular releases and to increment the right most (micro or patch) number for test versions or emergency bug fix releases. Community posted versions could also bump micro. I should have bumped the ME/QC/GrS micro version by 2, or bumped the minor version; I honestly didn't think about it until after I'd already released ME. FYI, semi-related, Github releases want Semantic Versioning (https://semver.org/) these days. Which does allow for extra specificity after the micro number, but doesn't want anything before the version number. To the point that I've found I have to use "Name 1.2.3" when naming releases because using "Name v1.2.3" can cause github to list releases out of order. And I do acknowledge that I put out FFF test versions more frequently than most plugins, and that using the micro number for that violates Semantic Versioning rules. We work with what we have.

Today, 01:27 PM	#4
PeterT Grand Sorcerer Posts: 13,643 Karma: 79983758 Join Date: Nov 2007 Location: Toronto Device: Libra H2O, Libra Colour	Hmmm... maybe adding a 4th number for a beta version will work. I just hacked an installed plugin on my system to be (1,14,3,1) and tried the plugin update in calibre. It correctly showed that version 1.14.3.1 was installed and that 1.14.4 was available. Changing the version to (1,14,4,1) shows that 1.14.4.1 is installed with no updates available, and that 1.14.4 is the available version. So I get the feeling that the simplest solutuon is for community members to leave the first three digits beinbg the version of the plugin they are basing their mod on, add that 4th digit, and to increase it if they do make additional changes.

Today, 02:23 PM	#5
JimmXinu Plugin Developer Posts: 7,083 Karma: 4604637 Join Date: Dec 2011 Location: Midwest USA Device: Kobo Clara Colour running KOReader	Perhaps 4 number version is more practical than I assumed. I'd also like to know what happens if someone does post a 4 number version plugin in a first post--it would likely happen at some point. I'm not sure anyone but Kovid has visibility into the server-side plugin system.

Today, 02:28 PM	#6
un_pogaz Chalut o/ Posts: 466 Karma: 678910 Join Date: Dec 2017 Device: Kobo	My norm is: Release, Major, Minor, Experimental. (with Experimental is optional) Note that the use of the fourth number must be reserved for private use, sharing a test version to the user, and so in the mind of a scope very limited in time. Any official version need to limite itself to the standard three number version. Incidentally, I like to increase my experimental versions by 100, so 1.2.5.100, 1.2.5.200... the advantage of this naming convention is that it clearly indicates that it is an experimental version, so it easy to catch into the log. Other advantage to put the experimental version into a fourth number is that when a official version is releasead, even with a minor/hotfix change, the official will naturaly overwrite the experimental one on the user side. In the goal of the initial question of the thread: the maintainer need to use the three version number. That avoid to confuse the random user that probaly don't know that the plugin has changed of lead developer, and if the original developer ever comes back, he simple have to catch up the version relesead during their absence.

Today, 02:34 PM	#7
DrChiper Bookish Posts: 1,043 Karma: 2006208 Join Date: Jun 2011 Device: PC, t1, t2, t3, Clara BW, Clara HD, Libra 2, Libra Color, Nxtpaper 11	So I am to understand that a developer/maintainer must use 1.14.3.0 on an officially release, and is the 1.14.3.1 etc. just for the community?

Today, 02:49 PM	#8
PeterT Grand Sorcerer Posts: 13,643 Karma: 79983758 Join Date: Nov 2007 Location: Toronto Device: Libra H2O, Libra Colour	Looks as if the cached Plugin index is created by setup/plugins_mirror.py and this code seems to work fine with a 4 digit version number in the plugin.