Einleitung
Ab Discourse-Version 3.2.0.beta3 können Discourse-Themes/Komponenten eine Migrationsfunktion nutzen, um ihre Einstellungen nahtlos weiterzuentwickeln und zu ändern. Diese Funktion stellt sicher, dass Updates von Themes bestehende Installationen nicht stören, indem Änderungen an Einstellungen auf kontrollierte Weise gehandhabt werden.
Wann Migrationen verwendet werden sollten
Häufige Szenarien, in denen Migrationen besonders nützlich sind:
- Ändern des Typs einer Einstellung (z. B. von einem durch Kommas getrennten String zu einer Liste).
- Umbenennen einer Einstellung.
- Ändern der Struktur oder des Formats der in einer Einstellung gespeicherten Daten.
In diesen Szenarien, wenn der Einstellungstyp oder -name in der Datei settings.yml ohne eine begleitende Migration geändert wird, verlieren bestehende Installationen, bei denen die Einstellung vom Standardwert geändert wurde, die vorgenommene Änderung und können beim Aktualisieren des Themes potenziell fehlschlagen.
Um einen reibungslosen Übergang bei der Aktualisierung einer Theme-Einstellung zu gewährleisten, sollten Theme-Entwickler eine Migration bereitstellen, die Discourse-Core anweist, wie der vorhandene Zustand, der der alten Version von settings.yml entspricht, in die neue Version migriert werden soll.
Migrationsdateien
Migrationen sind JavaScript-Dateien im Verzeichnis migrations/settings des Themes, die der Namenskonvention XXXX-migration-name.js folgen. Das Präfix XXXX ist eine Versionsnummer, beginnend mit 0001 und sequenziell inkrementiert, die die Ausführungsreihenfolge bestimmt.
Der Name sollte eine prägnante Beschreibung des Zwecks der Migration sein, beschränkt auf alphanumerische Zeichen, Bindestriche und unter 150 Zeichen Länge. Migrationen werden in aufsteigender Reihenfolge basierend auf dem numerischen Wert ihrer Versionen ausgeführt.
Wir empfehlen, mit 0001 für die erste Migration und 0002 für die zweite Migration usw. zu beginnen. Beachten Sie, dass, wenn die Version einer Migration unter 1000 liegt, die Version mit führenden Nullen aufgefüllt werden muss, um 4 Ziffern lang zu sein, da der Migrationsdateiname mit 4 Ziffern beginnen muss. Aus demselben Grund ist es derzeit nicht möglich, mehr als 9999 Migrationen in einem Theme zu haben, aber wir können dies in Zukunft ändern.
Migrationsfunktion
Standard-JavaScript-Features wie Klassen, Funktionen, Arrays, Maps usw. stehen Migrationen zur Verfügung. Die einzige Erwartung von Discourse-Core ist, dass jede Migrationsdatei eine Standardfunktion exportieren muss, die als Einstiegspunkt dient. Diese Funktion empfängt ein Map-Objekt, das geänderte Theme-Einstellungen darstellt, und gibt ein Map-Objekt zurück, das den gewünschten Endzustand aller Einstellungen widerspiegelt.
Beispiele
Umbenennen einer Theme-Einstellung:
// Dateiname: 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;
}
Diese Migration sollte mit der Umbenennung der Einstellung in der Datei settings.yml einhergehen.
Konvertieren eines durch Kommas getrennten String-Settings in eine richtige Liste:
// Dateiname: 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;
}
Ähnlich wie im vorherigen Beispiel sollte diese Migration mit der Änderung des Einstellungstyps von string zu list in der Datei settings.yml einhergehen.
Umbenennen einer Auswahl einer Enum-Einstellung:
// Dateiname: 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;
}
Hinzufügen eines neuen Elements zu einer Listen-Einstellung:
// Dateiname: 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;
}
Ausführung und Fehlerbehandlung
Migrationen werden automatisch während der Theme-Installation und -Updates ausgeführt. Sie werden nur einmal ausgeführt; wenn eine Migration nach erfolgreicher Ausführung geändert wird, wird sie nicht erneut ausgeführt. Wenn eine Migration fehlschlägt, wird der Update-Prozess gestoppt und eine Fehlermeldung darüber ausgegeben, was schief gelaufen ist.
Wenn eine Migration einen Fehler enthält, der zu einem beschädigten Zustand einer Einstellung führt, dann ist der richtige Weg, das Problem zu beheben, die Erstellung einer neuen Migration, die den beschädigten Zustand korrigiert, anstatt die ursprüngliche Migration zu ändern.
Dieses Dokument ist versionskontrolliert – schlagen Sie Änderungen auf github vor.