Version numbers in CMFQuickInstaller

published Apr 30, 2009, last modified Jun 16, 2009

A tale of two versions.

Note: this article has been copied to http://plone.org/documentation/how-to/version-numbers-in-cmfquickinstaller where it has more chance of being updated to keep pace with developments.

When you write an add-on package for Plone, there are currently two ways of writing an installer: a GenericSetup (GS) profile and an External Method (an install method in Extensions/install.py). The preference nowadays is for the GS profile; in fact, in the trunk of Plone (which will be Plone 4 in a year or so) a GS profile is the only way.

But meanwhile, when you go to the portal_quickinstaller (QI) in the ZMI, or the Add-On Products section in the Plone Site Setup (same QI, different user interface), you might see some confusing numbers. For example, you may have previously installed Products.FooBar 1.2 in your Plone Site and now you have upgraded it to version 1.3 on the file system and the quick installer tells you it has an upgrade available for "Profile for Foo Bar' from version 1.2 to 700. Or some other unexpected number, like a lower 1.0. What happened to Products.FooBar 1.3 that you just added to your buildout?

Well, first of all, this product apparently has a GS profile and the QI does not show the name of the package (Products.FooBar) but the (hopefully informative) name of the GS profile (Profile for Foo Bar). Fair enough. But what about those version numbers?

What happened here is that you actually do have the correct version 1.3 of the package, but the QI is showing the version of the GS profile, which can be wildly different from the package version. The idea behind the differing numbers is that this new package release only has some minor changes to for example some page templates. When there are no changes to the GS profile, there is no need to reinstall the package, or reapply the GS profile, so we keep the profile version the same. Since the package and profile version can be different, it is best to keep them different from the start. For the profile version it is fine to simply use increasing numbers: 1, 2, 3.

In this case, something has changed in the package and caused the profile version to be shown where previously the package version was used; or perhaps those numbers were the same in the previous release. For a better understanding, let's look at how the various CMFQuickInstaller releases handle version numbers. Handy conclusions are at the end.

In all versions:

  • The GS Profile name is shown, otherwise the package name is shown.
  • If the getProductVersion method of the QI cannot find a version, no version is shown.
  • Packages must be in the Products name space or use the five:registerPackage directive in zcml, otherwise they are not shown in the Product Management section of the Zope Control Panel.
  • For getting the version number from the version.txt file, the package must be listed in that Product Management section. For getting the version number from setup.py or from the GS profile (the metadata.xml file) this is not necessary.
  • Packages that rely on an external method (so no GS profile) for getting installed and that are not in the Product Management section, are not listed in the QI.
  • Note that the Products section of the Zope Control Panel only looks for version.txt, at least in Zope 2.10.

Plone 3.0

  • Plone 3.0.6 uses QI 2.0.4.
  • getProductVersion gets the version from version.txt only.
  • The GS Profile version is never shown.
  • Packages must be in the Products name space or use the five:registerPackage directive, otherwise they are not shown in the QI. Only with this QI version is this true both for packages with an external method and for packages with a GS profile.

Plone 3.1/3.2

  • Plone 3.1.7 and 3.2.2 use QI 2.1.6.
  • getProductVersion gets the version from version.txt; when that fails it gets the version from the GS profile.
  • Packages with a GS profile are always shown in the QI, also when they do not use five:registerPackage and are not in the Products name space.
  • When a GS profile version is found, this version is shown, except that when five:registerPackage is used (or the Products name space) and there is a version.txt, then that version is shown.

Plone 3.3

  • Plone 3.3rc2 uses QI 2.1.7.
  • getProductVersion gets the version from setup.py; else it gets the version from version.txt; it specifically does not get the version from the GS profile.
  • setup.cfg is also used, so if you have tag_build = dev in the egg_info section, the version will have 'dev' behind it.

Conclusion

It looks like the only way to have the same version number listed in all Plone 3.x versions is with version.txt. Follow these guidelines and (at least for the studied QI versions) the version number from version.txt is always shown:

  • Use the Products name space or use the five:registerPackage directive. (Tip: when using paster to create your package, answer yes to the question 'Are you creating a Zope 2 Product?')
  • Use a version.txt.
  • In the setup.py use the version number from version.txt as the package version.

With this strategy it is possible to use GS profile versions that are entirely different from the version of your package, without confusing users. Specifically, I think I will start using just integers for the GS profile versions, instead of the dotted numbers I mostly use now.

One last conclusion: for Plone 3.0 (QI 2.0) remember that if you only have a GS profile and no external install method, your package will not be shown in the QI so you will have to use the portal_setup tool instead to install your package.