Einführung
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 sie Änderungen an Einstellungen auf kontrollierte Weise behandelt.
Wann sollten Migrationen verwendet werden?
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 gehen bei bestehenden Installationen, bei denen die Einstellung vom Standardwert geändert wurde, die vorgenommenen Änderungen an der Einstellung verloren und es kann beim Aktualisieren des Themes zu Problemen kommen, wenn der Einstellungstyp oder -name in der Datei settings.yml ohne eine begleitende Migration geändert wird.
Um einen reibungslosen Übergang beim Aktualisieren einer Theme-Einstellung zu gewährleisten, sollten Theme-Entwickler eine Migration bereitstellen, die dem Discourse-Kern anweist, wie der bestehende Zustand, der der alten Version der settings.yml entspricht, in die neue Version migriert werden kann.
Migrationsdateien
Migrationen sind JavaScript-Dateien, die sich im Verzeichnis migrations/settings des Themes befinden und der Namenskonvention XXXX-migration-name.js folgen. Das Präfix XXXX ist eine Versionsnummer, beginnend mit 0001 und fortlaufend inkrementiert, die die Reihenfolge der Ausführung 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 auf 4 Ziffern aufgefüllt werden muss, 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, dies kann sich jedoch in Zukunft ändern.
Migrationsfunktion
Standardmäßige JavaScript-Funktionen wie Klassen, Funktionen, Arrays, Maps usw. stehen Migrationen zur Verfügung. Die einzige Erwartung vom Discourse-Kern ist, dass jede Migrationsdatei eine Standardfunktion exportiert, die als Einstiegspunkt dient. Diese Funktion erhält 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
Eine Theme-Einstellung umbenennen:
// 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;
}
Diese Migration sollte von der Umbenennung der Einstellung in der Datei settings.yml begleitet werden.
Eine durch Kommas getrennte String-Einstellung in eine ordnungsgemäße Liste umwandeln:
// 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;
}
Ähnlich wie im vorherigen Beispiel sollte diese Migration von der Änderung des Einstellungstyps von string auf list in der Datei settings.yml begleitet werden.
Eine Auswahl einer Enum-Einstellung umbenennen:
// 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;
}
Einem Listen-Setting ein neues Element hinzufügen:
// 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;
}
Ausführung und Fehlerbehandlung
Migrationen werden während der Theme-Installation und -Updates automatisch 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, was schiefgelaufen ist, wird bereitgestellt.
Wenn eine Migration einen Fehler enthält, der zu einem korrupten Zustand für eine Einstellung führt, besteht die richtige Vorgehensweise zur Behebung des Problems darin, eine neue Migration zu erstellen, die den korrupten Zustand korrigiert, anstatt die ursprüngliche Migration zu ändern.
Dieses Dokument wird versioniert – Änderungen auf github vorschlagen.