With a new version of Cinnamon coming out every 6 months, there might be some cool new feature you want to use in your applet. However, you also don't want to leave out the poor users using the older versions of Cinnamon.

Alternatively, when a new version of Cinnamon comes out, your extension is no longer compatible with it. Updating it would, again, leave out the users running older Cinnamons.

Here extension versioning comes to the rescue. As of Cinnamon 2.6, it is possible to ship different versions of your extension for different versions of Cinnamon. Here "extension" will refer to all extensions, applets and desklets.

The different versions should be put in different subdirectories. For example, the version for 2.6 should be put in extension@uuid/2.6/. The contents in 2.6/ should be exactly what you will normally put in extension@uuid/, apart from metadata.json, which should always be put in the parent directory, ie. extension@uuid/.

You do not need to create a subdirectory for every single Cinnamon version out there. Cinnamon looks for the most recent subdirectory that is not newer than the running Cinnamon version. For example, if you are running 2.6 and there are 2.4, 2.8 directories, the 2.4 directory will be loaded, until the you upgrade to 2.8 in which case the 2.8 directory will be used. Minor version numbers can also be used, eg. 2.6.4, and are sorted accordingly.

If no suitable directory is found, then the contents in extension@uuid/ will be loaded. Note that Cinnamon versions prior to 2.6 will not understand this directory magic, and will always try to load the contents in extension@uuid/. Hence it is suggested that extension maintainers put the version for 2.4 in extension@uuid, and create new directories if changes specific to newer Cinnamon versions are made. Don't make a new directory whenever a Cinnamon version is out since it is just a waste of space (and maintenance effort).

Note that this also allows you to support future versions of Cinnamon. For example, if you see a cool feature in the development branch of Cinnamon, you can modify your code and put it in the 2.6 folder (assuming the current version is 2.4). Then once the user upgrades their Cinnamon version, the new code will be used instead. This also allows extensions to be smoothly upgraded between versions.