Contesto
Gli sviluppatori di temi e plugin generalmente vogliono targeting l’ultima versione di Discourse, senza preoccuparsi della compatibilità retroattiva. Tuttavia, i siti che eseguono versioni precedenti di Discourse hanno ancora bisogno di una versione del tema/plugin che funzioni per loro.
Per colmare questo divario, è possibile istruire Discourse a verificare una versione ‘fissata’ (pinned) più vecchia del tema/plugin. Esistono due meccanismi per questo, controllati in ordine:
- Rami git
d-compat/<AAAA>.<M>nel repository del tema/plugin (il metodo principale — raccomandato per tutte le nuove fissazioni). - Un file YAML
.discourse-compatibilitynella radice del repository (il meccanismo originale, ancora supportato come fallback).
Se entrambi esistono, il ramo ha la precedenza.
Il sistema di rami d-compat/<AAAA>.<M>
Le release di Discourse utilizzano versioni basate sulla data, come 2025.5, 2025.6, ecc. Quando Discourse aggiorna un plugin o un tema da git, chiede al repository: “Hai un ramo chiamato d-compat/<AAAA>.<M> che corrisponde alla mia versione?” (ad esempio, d-compat/2025.5 per Discourse 2025.5.x). Se è così, Discourse esegue il checkout della punta di quel ramo invece di main.
La ricerca viene eseguita solo quando il checkout locale è sul ramo predefinito del repository. Se hai intenzionalmente fissato un altro ramo, la logica d-compat viene saltata e la tua fissazione viene rispettata.
Per supportare una versione più vecchia di Discourse con questo sistema:
- Crea un ramo chiamato
d-compat/<AAAA>.<M>da un commit noto per funzionare su quella versione (ad esempio,git checkout -b d-compat/2025.5 <commit>). - Spingilo su
origin. Potresti voler proteggere il ramo dalla cancellazione accidentale. - Applica eventuali commit di backport a quel ramo. Le istanze di Discourse su
2025.5.xli raccoglieranno automaticamente al prossimo aggiornamento; le istanze su versioni più recenti di Discourse continueranno a seguire il ramo predefinito.
Quando si utilizzano i rami, non è necessario toccare .discourse-compatibility.
Creazione automatizzata dei rami (create-d-compat-branch.yml)
In pratica, raramente è necessario creare questi rami a mano. Gli scheletri predefiniti per temi e plugin includono un workflow d-compat-branch.yml che viene eseguito quotidianamente, verifica le nuove versioni di Discourse core e spinge i rami d-compat/<AAAA>.<M> corrispondenti quando necessario.
Se il tuo repository è stato creato da una copia più vecchia degli scheletri, copia semplicemente il file d-compat-branch.yml nella directory .github/workflows per attivarlo.
Backport di una correzione a un ramo d-compat
Quando hai applicato una correzione sul ramo predefinito che deve anche raggiungere i siti su una release più vecchia di Discourse:
-
Crea un ramo dal ramo d-compat di destinazione e cherry-pick la correzione:
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 -
Apri una PR con
d-compat/2025.5come ramo di base (nonmain). Ottienine la revisione e la fusione allo stesso modo in cui faresti per qualsiasi altra PR. -
Ripeti per ogni ramo
d-compat/<AAAA>.<M>più vecchio che necessita della correzione.
I siti su 2025.5.x raccoglieranno il commit fuso al loro prossimo aggiornamento.
Fallback legacy: il file `.discourse-compatibility`
Se non esiste un ramo d-compat corrispondente, Discourse fa riferimento a un file YAML .discourse-compatibility nella radice del repository, che mappa le versioni di Discourse ai riferimenti git del tuo plugin/tema:
< 3.2.0.beta2-dev: abcde
Discourse seleziona la voce più bassa che corrisponde alla versione core in esecuzione, quindi chiunque sia su < 3.2.0.beta2-dev eseguirà il checkout del commit abcde. Usa < (o il legacy <=, il valore predefinito quando non viene specificato un operatore) per specificare il limite di versione. Ricorri a questo solo se il sistema basato su rami non può esprimere ciò di cui hai bisogno.
Questo documento è sotto controllo di versione - suggerisci modifiche su github.