Blocco delle versioni di plugin e temi per installazioni Discourse più vecchie (branch d-compat)

[Discourse]

Contesto

Gli sviluppatori di temi e plugin generalmente mirano a puntare alla versione latest di Discourse, senza doversi preoccupare della compatibilità con le versioni precedenti. Tuttavia, i siti che eseguono versioni più vecchie di Discourse hanno comunque bisogno di una versione del tema/plugin che funzioni per loro.

Per colmare questo divario, è possibile istruire Discourse a prelevare una versione “bloccata” (pinned) più vecchia del tema/plugin. Esistono due meccanismi per farlo, verificati in quest’ordine:

1. Branch git d-compat/<YYYY>.<M> nel repository del tema/plugin (il metodo principale — raccomandato per tutti i nuovi blocchi).
2. Un file YAML .discourse-compatibility nella radice del repository (il meccanismo originale, ancora supportato come fallback).

Se entrambi esistono, prevale il branch.

Il sistema di branch d-compat/<YYYY>.<M>

Le versioni di Discourse utilizzano numeri basati sulla data, come 2025.5, 2025.6, ecc. Quando Discourse aggiorna un plugin o un tema da git, chiede al repository: «Hai un branch chiamato d-compat/<YYYY>.<M> che corrisponde alla mia versione?» (ad esempio d-compat/2025.5 per Discourse 2025.5.x). Se sì, Discourse preleva l’ultimo commit di quel branch invece di main.

La ricerca viene eseguita solo quando la copia locale si trova sul branch predefinito del repository. Se hai intenzionalmente bloccato il progetto su un branch diverso, la logica d-compat viene saltata e il tuo blocco viene rispettato.

Per supportare una versione più vecchia di Discourse con questo sistema:

1. Crea un branch chiamato d-compat/<YYYY>.<M> partendo da un commit noto per funzionare su quella versione (ad esempio git checkout -b d-compat/2025.5 <commit>).
2. Spingilo su origin. Potresti voler proteggere il branch da cancellazioni accidentali.
3. Apporta eventuali commit di backport su quel branch. Le istanze di Discourse su 2025.5.x li rileveranno automaticamente al prossimo aggiornamento; le istanze su versioni più recenti di Discourse continueranno a seguire il branch predefinito.

Quando si utilizzano i branch, non è necessario toccare affatto il file .discourse-compatibility.

Creazione automatizzata dei branch (create-d-compat-branch.yml)

In pratica, raramente è necessario creare questi branch manualmente. Gli scheletri predefiniti per temi e plugin includono un workflow d-compat-branch.yml che viene eseguito quotidianamente, verifica la presenza di nuove versioni del core di Discourse e spinge i branch d-compat/<YYYY>.<M> corrispondenti, se necessario.

Se il tuo repository è stato creato da una copia più vecchia degli scheletri, copia semplicemente il file d-compat-branch.yml nella tua directory .github/workflows per farlo funzionare.

Backport di una correzione su un branch d-compat

Quando hai applicato una correzione sul branch predefinito che deve raggiungere anche i siti in esecuzione su una versione più vecchia di Discourse:

1. Crea un branch dal branch d-compat di destinazione e fai uno cherry-pick della 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
   

2. Apri una PR impostando d-compat/2025.5 come branch di base (non main). Fàla revisionare e unire nello stesso modo in cui faresti per qualsiasi altra PR.

3. Ripeti per ogni branch d-compat/<YYYY>.<M> più vecchio che necessita della correzione.

I siti su 2025.5.x riceveranno il commit unito al loro prossimo aggiornamento.

Fallback legacy: il file `.discourse-compatibility`

Se non esiste un branch d-compat corrispondente, Discourse ricorre 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 del core in esecuzione, quindi chiunque sia su < 3.2.0.beta2-dev preleverà il commit abcde. Usa < (o il legacy <=, che è il default quando non viene fornito un operatore) per specificare il limite di versione. Ricorri a questo metodo solo se il sistema basato sui branch non riesce a esprimere ciò di cui hai bisogno.

---

Questo documento è sottoposto a controllo versione — suggerisci modifiche su GitHub.

[NateDhaliwal]

Se la versione è \u003c 3.5.0.beta8-dev, includerebbe 3.5.0?

[david (David Taylor)]

No. 3.5.0 è considerato “superiore” alla versione prerelease “3.5.0.beta8-dev”.

Puoi sempre provare i confronti su una console ruby:

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

[NateDhaliwal]

Capito. Grazie per la spiegazione!

[david (David Taylor)]

Questo documento è stato aggiornato per descrivere la nuova strategia d-compat/* da RFC: A new versioning strategy for Discourse, ora disponibile per l’uso.