Migrare le impostazioni del tema Discourse

Documentazione Guide per sviluppatori
1

Introduzione

A partire dalla versione 3.2.0.beta3 di Discourse, i temi/componenti di Discourse possono sfruttare una funzionalità di migrazione per evolvere e modificare le proprie impostazioni in modo trasparente. Questa funzionalità garantisce che gli aggiornamenti dei temi non interrompano le installazioni esistenti gestendo le modifiche alle impostazioni in modo controllato.

Quando usare le migrazioni

Scenari comuni in cui le migrazioni sono particolarmente utili:

  • Modifica del tipo di un’impostazione (ad esempio, da una stringa separata da virgole a un elenco).
  • Ridenominazione di un’impostazione.
  • Modifica della struttura o del formato dei dati memorizzati in un’impostazione.

In questi scenari, se il tipo o il nome dell’impostazione viene modificato nel file settings.yml senza una migrazione associata, le installazioni esistenti in cui l’impostazione è stata modificata rispetto al valore predefinito perderanno la modifica apportata e potenzialmente si romperanno quando il tema verrà aggiornato.

Per garantire una transizione fluida durante l’aggiornamento di un’impostazione del tema, gli sviluppatori del tema dovrebbero fornire una migrazione che istruisca Discourse core su come migrare lo stato esistente che è conforme alla vecchia versione di settings.yml alla nuova versione.

File di migrazione

Le migrazioni sono file JavaScript situati nella directory migrations/settings del tema, seguendo la convenzione di denominazione XXXX-nome-migrazione.js. Il prefisso XXXX è un numero di versione, a partire da 0001 e incrementando sequenzialmente, che determina l’ordine di esecuzione.

Il nome deve essere una descrizione concisa dello scopo della migrazione, limitato a caratteri alfanumerici, trattini e meno di 150 caratteri. Le migrazioni vengono eseguite in ordine crescente in base al valore numerico delle loro versioni.

Si consiglia di iniziare con 0001 per la prima migrazione e 0002 per la seconda migrazione, ecc. Si noti che se la versione di una migrazione è inferiore a 1000, la versione deve essere riempita con zeri iniziali per renderla lunga 4 cifre poiché il nome del file di migrazione deve iniziare con 4 cifre. Per lo stesso motivo, attualmente non è possibile avere più di 9999 migrazioni in un tema, ma potremmo cambiarlo in futuro.

Funzione di migrazione

Funzionalità JavaScript standard funzionalità come classi, funzioni, array, mappe, ecc. sono tutte disponibili per l’uso nelle migrazioni. L’unica aspettativa da parte di Discourse core è che ogni file di migrazione deve esportare una funzione predefinita che funge da punto di ingresso. Questa funzione riceve un oggetto Map che rappresenta le impostazioni del tema modificate e restituisce un oggetto Map che riflette lo stato finale desiderato di tutte le impostazioni.

Esempi

Rinomina un’impostazione del tema:

// nome file: 0001-rinomina-vecchia-impostazione.js

export default function migrate(settings) {
  if (settings.has("nome_vecchia_impostazione")) {
    settings.set("nome_nuova_impostazione", settings.get("nome_vecchia_impostazione"));
    settings.delete("nome_vecchia_impostazione");
  }
  return settings;
}

Questa migrazione dovrebbe essere accompagnata dalla ridenominazione dell’impostazione nel file settings.yml.

Converti un’impostazione di stringa separata da virgole in un elenco corretto:

// nome file: 0001-converti-stringa-impostazione-in-elenco.js

export default function migrate(settings) {
  if (settings.has("impostazione_elenco")) {
    const list = settings.get("impostazione_elenco").split(",");
    settings.set("impostazione_elenco", list.join("|"));
  }
  return settings;
}

Simile all’esempio precedente, questa migrazione dovrebbe essere accompagnata dalla modifica del tipo di impostazione da string a list nel file settings.yml.

Rinomina una scelta di un’impostazione enum:

// nome file: 0001-rinomina-scelta-enum.js

export default function migrate(settings) {
  if (settings.get("impostazione_enum") === "vecchia_opzione") {
    settings.set("impostazione_enum", "nuova_opzione");
  }
  return settings;
}

Aggiungi un nuovo elemento a un’impostazione di elenco:

// nome file: 0001-aggiungi-elemento-a-elenco.js

export default function migrate(settings) {
  if (settings.has("impostazione_elenco")) {
    const list = settings.get("impostazione_elenco").split("|");
    list.push("nuovo_elemento");
    settings.set("impostazione_elenco", list.join("|"));
  } else {
    settings.set("impostazione_elenco", "nuovo_elemento");
  }
  return settings;
}

Esecuzione e gestione degli errori

Le migrazioni vengono eseguite automaticamente durante l’installazione e gli aggiornamenti dei temi. Vengono eseguite una sola volta; se una migrazione viene modificata dopo l’esecuzione corretta, non verrà eseguita di nuovo. Se una migrazione fallisce, il processo di aggiornamento si interrompe e viene fornito un messaggio di errore su cosa è andato storto.

Se una migrazione contiene un bug che causa uno stato corrotto per un’impostazione, il modo corretto per risolvere il problema è creare una nuova migrazione che corregga lo stato corrotto invece di modificare la migrazione originale.

Questo documento è controllato dalla versione - suggerisci modifiche su github.

8 Mi Piace