Plugin/Theme Version Numbering

Hi all,

There has been some confusion over how plugin and theme version numbering works and which fields need changing. So I’m posting this thread as the definitive resource - we’ll add it to the Knowledge Base/docs too.

Note: this may be different to what you’ve been told previously, but as far as I can tell the following information has been correct since at least RapidWeaver 5 (which is the furthest I can go back in the RapidWeaver codebase).

When comparing releases, we’ll look at the CFBundleVersion field in your addon’s Info.plist file. If this isn’t increased, we’ll assume it’s not an updated addon. Apple has this to say about CFBundleVersion:

CFBundleVersion (String - iOS, OS X) specifies the build version number of the bundle, which identifies an iteration (released or unreleased) of the bundle. The build version number should be a string comprised of three non-negative, period-separated integers with the first integer being greater than zero. The string should only contain numeric (0-9) and period (.) characters. Leading zeros are truncated from each integer and will be ignored (that is, 1.02.3 is equivalent to 1.2.3). This key is not localizable.

When displaying the version string to users, we’ll use CFBundleShortVersionString. This isn’t used for calculating updates - it’s only used in UI. Apple has this to say:

CFBundleShortVersionString (String - iOS, OS X) specifies the release version number of the bundle, which identifies a released iteration of the app. The release version number is a string comprised of three period-separated integers. The first integer represents major revisions to the app, such as revisions that implement new features or major changes. The second integer denotes revisions that implement less prominent features. The third integer represents maintenance releases.

The value for this key differs from the value for CFBundleVersion, which identifies an iteration (released or unreleased) of the app. This key can be localized by including it in your InfoPlist.strings files.

In most cases you’ll want these to be the same value.

When comparing version numbers, no other fields are used. To be totally clear, do not use RWVersion in your Theme.plist file.

Plugins should also set the RWPluginAPIVersion field in their Info.plist and we’ll change certain behaviour based on their selection. This does not increment in line with the RapidWeaver release version. Unless you have a very good reason, this should be set to 4.


Hey @simon

Thanks for the well written explanation. Unfortunately though I’ve been using CFBundleVersion for updates and RW still thinks that the new version of a theme is the same as a previous version. The CFBundleVersion for the original theme is 100 and the update’s CFBundleVersion is 101. Being that 101 is higher than 100 it should not think they’re the same during installation, yet it does. I have tried using 1.0.0 and 1.0.1 for the CFBundleVersion as suggested above, but also run into the same problem:

If you need anything to replicate this, let me know. You should be able to just adjust version numbers in a theme’s info.plist file though to achieve this problem.

RW v7.0.4
Build 17842
OS X 10.11.5

Can you send me a copy of the new and old versions of the plugins and I’ll take a look?

Sure thing @simon, not a problem. Here’s a ZIP with both:

Hi @Elixir. Ok, I’ve managed to replicate the issue here and it’ll be fixed for the next 7.1 beta.

If you want to fix it temporarily in 7.0.x, you should add the version keys to Theme.plist too. This was a bug introduced in 7.0 with the new add-on installer :unamused:

Good to hear. Thought I was losing my mind. Adding it into the theme.plist file won’t help at this point since the original theme is already distributed. People will just need instruction to ignore RW’s message saying that the new theme is the same as the old one.

1 Like