Contexte
Les développeurs de thèmes et de plugins souhaitent généralement cibler la version latest de Discourse, sans se soucier de la rétrocompatibilité. Cependant, les sites fonctionnant avec des versions plus anciennes de Discourse ont toujours besoin d’une version du thème/plugin qui fonctionne pour eux.
Pour combler cet écart, Discourse peut être configuré pour vérifier une version « épinglée » plus ancienne du thème/plugin. Il existe deux mécanismes pour cela, vérifiés dans l’ordre suivant :
- Les branches git
d-compat/<AAAA>.<M>dans le dépôt du thème/plugin (la méthode principale — recommandée pour tous les nouveaux épinglements). - Un fichier YAML
.discourse-compatibilityà la racine du dépôt (le mécanisme d’origine, toujours pris en charge en tant que solution de repli).
Si les deux existent, la branche prévaut.
Le système de branches d-compat/<AAAA>.<M>
Les versions de Discourse utilisent des numéros basés sur la date, comme 2025.5, 2025.6, etc. Lorsque Discourse met à jour un plugin ou un thème depuis git, il interroge le dépôt : « avez-vous une branche nommée d-compat/<AAAA>.<M> correspondant à ma version ? » (par exemple, d-compat/2025.5 pour Discourse 2025.5.x). Si oui, Discourse vérifie l’extrémité de cette branche au lieu de main.
La recherche ne s’exécute que lorsque la vérification locale se trouve sur la branche par défaut du dépôt. Si vous avez volontairement épinglé à une autre branche, la logique d-compat est ignorée et votre épinglement est respecté.
Pour prendre en charge une version plus ancienne de Discourse avec ce système :
- Créez une branche nommée
d-compat/<AAAA>.<M>à partir d’un commit connu pour fonctionner sur cette version (par exemple,git checkout -b d-compat/2025.5 <commit>). - Poussez-la vers
origin. Vous pouvez souhaiter protéger la branche contre la suppression accidentelle. - Intégrez les commits de rétroportage sur cette branche. Les instances Discourse sur
2025.5.xles récupéreront automatiquement lors de la prochaine mise à jour ; les instances sur des versions plus récentes de Discourse continueront de suivre la branche par défaut.
Vous n’avez pas besoin de toucher au fichier .discourse-compatibility lorsque vous utilisez des branches.
Création automatisée de branches (create-d-compat-branch.yml)
En pratique, vous avez rarement besoin de créer ces branches manuellement. Les squelettes de thèmes et de plugins par défaut incluent un workflow d-compat-branch.yml qui s’exécute quotidiennement, vérifie les nouvelles versions du cœur de Discourse et pousse les branches d-compat/<AAAA>.<M> correspondantes si nécessaire.
Si votre dépôt a été créé à partir d’une copie plus ancienne des squelettes, copiez simplement le fichier d-compat-branch.yml dans votre répertoire .github/workflows pour le faire fonctionner.
Rétroportage d’un correctif sur une branche d-compat
Lorsque vous avez intégré un correctif sur la branche par défaut qui doit également atteindre les sites sur une version plus ancienne de Discourse :
-
Créez une branche à partir de la branche d-compat cible et effectuez un cherry-pick du correctif :
git fetch origin git checkout -b backport/my-fix-2025.5 origin/d-compat/2025.5 git cherry-pick <commit-sha> git push -u origin backport/my-fix-2025.5 -
Ouvrez une PR avec
d-compat/2025.5comme branche de base (et nonmain). Faites-la réviser et fusionnez-la de la même manière que n’importe quelle autre PR. -
Répétez l’opération pour chaque branche
d-compat/<AAAA>.<M>plus ancienne qui a besoin du correctif.
Les sites sur 2025.5.x récupéreront le commit fusionné lors de leur prochaine mise à jour.
Solution de repli legacy : le fichier `.discourse-compatibility`
Si aucune branche d-compat correspondante n’existe, Discourse se rabat sur un fichier YAML .discourse-compatibility à la racine du dépôt, qui associe les versions de Discourse aux références git de votre plugin/thème :
< 3.2.0.beta2-dev: abcde
Discourse sélectionne la plus basse entrée qui correspond à la version du cœur en cours d’exécution, de sorte que quiconque est sur < 3.2.0.beta2-dev vérifie le commit abcde. Utilisez < (ou le <= legacy, la valeur par défaut lorsqu’aucun opérateur n’est donné) pour spécifier la borne de version. N’utilisez cela que si le système basé sur les branches ne peut pas exprimer ce dont vous avez besoin.
Ce document est sous contrôle de version - suggérez des modifications sur github.