Hey everyone , I just merged a new feature that will help plugins and themes pin certain versions when installed on older Discourse instances.
You can now include a
.discourse-compatibility file at the root of a plugin or theme repository, that designates what to checkout when installing on older Discourse versions.
It sucks to remember which plugins and themes are compatible with which Discourse versions. As an admin, it should be possible to easily scan those changes and find a version that is right for your Discourse install without reading through plugin commit history. As a plugin or theme author, it should be possible to manage install versions while making backwards-incompatible changes so you don’t break older installs.
Discourse software updates roll out pretty quickly, which while awesome, makes for maintaining Discourse instances with a lot of plugins sometimes very difficult, especially if you are following other release cadences/versions such as the current stable. My plan here is to allow an ecosystem that eases the update process for those following either stable or some other release cadence, and give those site admins a method to quickly and automatically grab whatever plugin version was compatible for the Discourse version they are targeting.
First thing to note: We are depending on Discourse core’s tags here, as Discourse’s betas ship frequently enough that we can pin plugin versions against them. Pinning against git hashes is a nightmare for a lot of reasons so we can git describe to get the closest beta/stable tag.
In a plugin or a theme, we now support a version compatibility file named
.discourse-compatibility at the root. This file is a descending (newer Discourse versions first) ordered list that specifies a compatibility map.
2.5.0.beta2: git-hash-1234e5f5d 2.4.4.beta6: 4444ffff33dd 2.4.2.beta1: named-git-tag-or-branch
For each plugin/theme an upgrade or rebuild will continue to checkout a later named commit/branch/tag until it finds one that is equal to, or later than the current Discourse version.
eg, for the above version file, if the current Discourse version was
2.4.6.beta12 it would scan the file and choose the entry for
If the current Discourse version was
2.4.4.beta6 it would choose the matching entry for
If no later version exists it stays on the current checked out version.
2.5.0.beta3 no pinning would occur.
if no earlier version exists, it checks out the earliest one listed in the version file.
2.2.1.beta22 it’d check out the earliest possible given “version”, the entry for
The aim here is to ease the pain of maintaining alternate deployments that are not strictly on tests-passed in the future, and give flexibility to admins for when and where to upgrade. We’re doing this by allowing plugin and theme authors a way to develop backwards-incompatible changes without affecting installs on older versions of Discourse.