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.
Rationale
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.
Original Announcement (now superseded by documentation linked above)
Implementation
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.
Example
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 2.5.0.beta2
.
If the current Discourse version was 2.4.4.beta6
it would choose the matching entry for 2.4.4.beta6
.
If no later version exists it stays on the current checked out version.
eg, for 2.5.0.beta3
no pinning would occur.
if no earlier version exists, it checks out the earliest one listed in the version file.
eg, for 2.2.1.beta22
itād check out the earliest possible given āversionā, the entry for 2.4.2.beta1
.
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.