Épinglage des versions des plugins et thèmes pour les anciennes installations de Discourse (branches d-compat)

[Discourse]

Contexte

Les développeurs de thèmes et de plugins visent généralement la version latest de Discourse, sans se soucier de la rétrocompatibilité. Cependant, les sites exécutant d’anciennes versions de Discourse ont toujours besoin d’une version du thème ou du plugin qui leur convienne.

Pour combler cette lacune, il est possible de demander à Discourse de vérifier une version « épinglée » plus ancienne du thème ou du plugin. Deux mécanismes sont disponibles, vérifiés dans l’ordre suivant :

1. Branches git d-compat/<YYYY>.<M> dans le dépôt du thème ou du plugin (méthode principale — recommandée pour tous les nouveaux épinglages).
2. Un fichier YAML .discourse-compatibility à la racine du dépôt (mécanisme original, toujours pris en charge en secours).

Si les deux existent, la branche l’emporte.

Le système de branches d-compat/<YYYY>.<M>

Les versions de Discourse utilisent des numéros basés sur la date, tels que 2025.5, 2025.6, etc. Lorsque Discourse met à jour un plugin ou un thème depuis git, il interroge le dépôt : « Disposez-vous d’une branche nommée d-compat/<YYYY>.<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.

Cette recherche ne s’exécute que si la copie locale se trouve sur la branche par défaut du dépôt. Si vous avez intentionnellement épinglé une autre branche, la logique d-compat est ignorée et votre épinglage est respecté.

Pour prendre en charge une ancienne version de Discourse avec ce système :

1. Créez une branche nommée d-compat/<YYYY>.<M> à partir d’un commit connu pour fonctionner sur cette version (par exemple git checkout -b d-compat/2025.5 <commit>).
2. Poussez-la vers origin. Vous voudrez peut-être protéger cette branche contre une suppression accidentelle.
3. Appliquez tout commit de rétroportage sur cette branche. Les instances Discourse sous 2025.5.x les récupéreront automatiquement lors de la prochaine mise à jour ; les instances sous des versions plus récentes 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 automatique de branches (create-d-compat-branch.yml)

En pratique, vous avez rarement besoin de créer ces branches manuellement. Les squelettes par défaut de thèmes et de plugins incluent un workflow d-compat-branch.yml qui s’exécute quotidiennement, vérifie les nouvelles versions du noyau Discourse et pousse les branches d-compat/<YYYY>.<M> correspondantes si nécessaire.

Si votre dépôt a été créé à partir d’une version plus ancienne des squelettes, copiez simplement le fichier d-compat-branch.yml dans votre répertoire .github/workflows pour le rendre fonctionnel.

Rétroportage d’une correction vers une branche d-compat

Lorsque vous avez appliqué une correction sur la branche par défaut qui doit également atteindre les sites sous une ancienne version de Discourse :

1. Créez une branche à partir de la branche d-compat cible et effectuez un cherry-pick de la correction :

   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
   

2. Ouvrez une PR avec d-compat/2025.5 comme branche de base (et non main). Faites-la examiner et fusionner de la même manière que n’importe quelle autre PR.

3. Répétez l’opération pour chaque ancienne branche d-compat/<YYYY>.<M> nécessitant la correction.

Les sites sous 2025.5.x récupéreront le commit fusionné lors de leur prochaine mise à jour.

Secours hérité : le fichier `.discourse-compatibility`

Si aucune branche d-compat correspondante n’existe, Discourse bascule vers 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 ou thème :

< 3.2.0.beta2-dev: abcde

Discourse sélectionne l’entrée la plus basse correspondant à la version du noyau en cours d’exécution. Ainsi, toute personne sous < 3.2.0.beta2-dev vérifiera le commit abcde. Utilisez < (ou l’opérateur hérité <=, par défaut lorsqu’aucun opérateur n’est fourni) pour spécifier la limite de version. N’utilisez cette méthode 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 — proposez des modifications sur GitHub.

[NateDhaliwal]

Si la version est < 3.5.0.beta8-dev, inclurait-elle 3.5.0 ?

[david (David Taylor)]

Non. 3.5.0 est considéré comme « supérieur » à la version prerelease « 3.5.0.beta8-dev ».

Vous pouvez toujours essayer des comparaisons sur une console ruby :

> Gem::Version.new("3.5.0") < Gem::Version.new("3.5.0.beta8-dev")
=> false

[NateDhaliwal]

Compris. Merci pour l’explication !

[david (David Taylor)]

Ce document a été mis à jour pour décrire la nouvelle stratégie d-compat/* issue de RFC: A new versioning strategy for Discourse, désormais disponible à l’usage.