Migra le impostazioni del tema di Discourse

Introduzione

A partire da Discourse versione 3.2.0.beta3, i componenti e i temi di Discourse possono sfruttare una funzionalità di migrazione per far evolvere e modificare le loro 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:

  • Modificare il tipo di un’impostazione (ad esempio, da una stringa separata da virgole a un elenco).
  • Rinominare un’impostazione.
  • Modificare la struttura o il formato dei dati archiviati in un’impostazione.

In questi scenari, se il tipo o il nome dell’impostazione viene modificato nel file settings.yml senza una migrazione corrispondente, nelle installazioni esistenti in cui l’impostazione è stata modificata rispetto al valore predefinito, si perderà la modifica apportata all’impostazione e l’aggiornamento del tema potrebbe causare errori.

Per garantire una transizione fluida durante l’aggiornamento di un’impostazione del tema, gli sviluppatori di temi dovrebbero fornire una migrazione che istruisca il core di Discourse su come migrare lo stato esistente 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, che seguono la convenzione di denominazione XXXX-nome-migrazione.js. Il prefisso XXXX è un numero di versione, a partire da 0001 e incrementato sequenzialmente, che detta l’ordine di esecuzione.

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

Consigliamo di iniziare con 0001 per la prima migrazione e 0002 per la seconda migrazione, e così via. Nota che se la versione di una migrazione è inferiore a 1000, la versione deve essere preceduta da zeri iniziali per raggiungere 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 questo potrebbe cambiare in futuro.

Funzione di migrazione

Le funzionalità JavaScript standard come classi, funzioni, array, mappe, ecc. sono tutte disponibili per l’uso nelle migrazioni. L’unica aspettativa da parte del core di Discourse è che ogni file di migrazione debba esportare una funzione predefinita che serve come 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

Rinominare un’impostazione del tema:

// filename: 0001-rename-old-setting.js

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

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


Convertire un’impostazione stringa separata da virgole in un elenco appropriato:

// filename: 0001-convert-string-setting-to-list.js

export default function migrate(settings) {
  if (settings.has("list_setting")) {
    const list = settings.get("list_setting").split(",");
    settings.set("list_setting", 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.


Rinominare una scelta di un’impostazione enum:

// filename: 0001-rename-enum-choice.js

export default function migrate(settings) {
  if (settings.get("enum_setting") === "old_option") {
    settings.set("enum_setting", "new_option");
  }
  return settings;
}

Aggiungere un nuovo elemento a un’impostazione elenco:

// filename: 0001-add-item-to-list.js

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

Spostare un’impostazione di testo in una traduzione del tema

Usa helpers.migrateSettingToTranslation(nomeImpostazione, chiaveTraduzione) quando sostituisci un’impostazione stringa con una traduzione del tema:

// filename: 0002-migrate-heading.js
export default function migrate(settings, helpers) {
  helpers.migrateSettingToTranslation("heading_text", "homepage.heading");
  return settings;
}

Rimuovi heading_text da settings.yml e dichiara la destinazione in locales/en.yml nello stesso aggiornamento:

en:
  homepage:
    heading: ""

L’helper sposta un’impostazione salvata in una sovrascrittura della traduzione del tema inglese e rimuove l’impostazione. L’inglese è la locale di fallback per altre lingue, quindi i visitatori continuano a vedere il testo salvato fino a quando non viene fornita una traduzione per la loro locale. Un file locale che dichiara la stessa chiave, anche con un valore vuoto, nasconde quel testo inglese salvato per la sua locale. Questo vale anche per i file locali aggiunti in futuri aggiornamenti.

  • L’helper legge dalla mappa settings passata alla migrazione. Vengono migrate solo le impostazioni salvate. Se la vecchia impostazione aveva un default non vuoto, usa quel default in en.yml così che i siti senza un valore salvato mantengano il loro testo.
  • Il valore dell’impostazione deve essere una stringa e la destinazione deve essere una chiave di testo dichiarata. Le stringhe vuote vengono preservate.
  • Le sovrascritture inglesi esistenti, incluse quelle vuote, non vengono sovrascritte. Se più migrazioni prendono di mira la stessa chiave, vince il primo valore migrato.
  • L’esecutore prepara le modifiche alla traduzione senza scrivere nel database. Discourse le salva nella stessa transazione delle impostazioni e dei record di migrazione; un aggiornamento fallito annulla il rollback di tutto.
  • Il log della migrazione conserva il valore dell’impostazione eliminata. Annullare il codice del tema non riporta le sovrascritture della traduzione nelle impostazioni.

Esecuzione e gestione degli errori

Le migrazioni vengono eseguite automaticamente durante l’installazione e gli aggiornamenti del tema. Vengono eseguite solo una volta; se una migrazione viene alterata dopo l’esecuzione riuscita, non verrà eseguita di nuovo. Se una migrazione fallisce, il processo di aggiornamento si arresta e viene fornito un messaggio di errore su ciò che non ha funzionato.

Se una migrazione ha un bug che risulta in 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 è sotto controllo di versione - suggerisci modifiche su github.

9 Mi Piace