Discourse-Theme-Einstellungen migrieren

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 Änderungen an den Einstellungen auf kontrollierte Weise behandelt werden.

Wann Migrationsfunktionen verwendet werden sollten

Typische Szenarien, in denen Migrationsfunktionen besonders nützlich sind:

  • Änderung des Typs einer Einstellung (z. B. von einer kommagetrennten Zeichenkette in eine Liste).
  • Umbenennung einer Einstellung.
  • Änderung der Struktur oder des Formats der in einer Einstellung gespeicherten Daten.

In diesen Szenarien werden bei bestehenden Installationen, in denen die Einstellung vom Standardwert abgewichen wurde, die vorgenommenen Änderungen an der Einstellung verloren gehen und das Theme potentially bricht, wenn der Typ oder der Name der Einstellung in der settings.yml-Datei ohne eine begleitende Migration geändert wird.

Um einen reibungslosen Übergang beim Aktualisieren einer Theme-Einstellung sicherzustellen, sollten Theme-Entwickler eine Migration bereitstellen, die Discourse-Core 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 im Verzeichnis migrations/settings des Themes, die der Namenskonvention XXXX-migrations-name.js folgen. Das Präfix XXXX ist eine Versionsnummer, beginnend bei 0001 und sequenziell steigend, welche die Ausführungsreihenfolge bestimmt.

Der Name sollte eine prägnante Beschreibung des Zwecks der Migration sein, begrenzt 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 die Versionsnummer mit führenden Nullen auf 4 Stellen aufgefüllt werden muss, wenn die Version einer Migration unter 1000 liegt, da der Dateiname der Migration mit 4 Ziffern beginnen muss. Aus diesem Grund ist es derzeit nicht möglich, mehr als 9999 Migrationen in einem Theme zu haben, aber dies könnte in der Zukunft geändert werden.

Migrationsfunktion

Standard-JavaScript-Funktionen wie Klassen, Funktionen, Arrays, Maps usw. stehen allen Migrationen zur Verfügung. Die einzige Erwartung von Discourse-Core ist, dass jede Migrationsdatei eine Standardfunktion exportieren muss, die als Einstiegspunkt dient. Diese Funktion erhält ein Map-Objekt, das die geänderten Theme-Einstellungen darstellt, und gibt ein Map-Objekt zurück, das den gewünschten Endzustand aller Einstellungen widerspiegelt.

Beispiele

Umbenennen einer Theme-Einstellung:

// 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 settings.yml-Datei begleitet werden.


Konvertieren einer kommagetrennten Zeichenketten-Einstellung in eine ordentliche Liste:

// 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 in list in der settings.yml-Datei begleitet werden.


Umbenennen einer Auswahl einer Enum-Einstellung:

// 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;
}

Hinzufügen eines neuen Elements zu einer Listen-Einstellung:

// 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;
}

Verschieben einer Text-Einstellung in eine Theme-Übersetzung

Verwenden Sie helpers.migrateSettingToTranslation(settingName, translationKey), wenn Sie eine Zeichenketten-Einstellung durch eine Theme-Übersetzung ersetzen:

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

Entfernen Sie heading_text aus settings.yml und deklarieren Sie das Ziel in locales/en.yml im selben Update:

en:
  homepage:
    heading: ""

Der Helper verschiebt eine gespeicherte Einstellung in einen englischen Theme-Übersetzungs-Override und entfernt die Einstellung. Englisch ist die Fallback-Sprache für andere Sprachen, so dass Besucher weiterhin den gespeicherten Text sehen, bis eine Übersetzung für ihre Sprache bereitgestellt wird. Eine Sprachdatei, die denselben Schlüssel deklariert, auch mit einem leeren Wert, verbirgt diesen gespeicherten englischen Text für ihre Sprache. Dies gilt auch für Sprachdateien, die in zukünftigen Updates hinzugefügt werden.

  • Der Helper liest aus der settings-Map, die an die Migration übergeben wird. Nur gespeicherte Einstellungen werden migriert. Wenn die alte Einstellung einen nicht-leeren Standardwert hatte, verwenden Sie diesen Standardwert in en.yml, damit Seiten ohne gespeicherten Wert ihren Text behalten.
  • Der Einstellungswert muss eine Zeichenkette sein und das Ziel muss ein deklarierter Textschlüssel sein. Leere Zeichenketten bleiben erhalten.
  • Bestehende englische Overrides, einschließlich leerer, werden nicht überschrieben. Wenn mehrere Migrationen auf denselben Schlüssel abzielen, gewinnt der zuerst migrierte Wert.
  • Der Runner stellt Übersetzungsänderungen bereit, ohne in die Datenbank zu schreiben. Discourse speichert sie in derselben Transaktion wie die Einstellungen und Migrationsdatensätze; ein fehlgeschlagenes Update rollt alles zurück.
  • Das Migrationsprotokoll behält den Wert der gelöschten Einstellung bei. Das Zurücksetzen des Theme-Codes verschiebt Übersetzungs-Overrides nicht wieder in die Einstellungen.

Ausführung und Fehlerbehandlung

Migrationen werden automatisch während der Theme-Installation und -Aktualisierung ausgeführt. Sie werden nur einmal ausgeführt; wenn eine Migration nach einer erfolgreichen Ausführung geändert wird, wird sie nicht erneut ausgeführt. Wenn eine Migration fehlschlägt, wird der Aktualisierungsprozess angehalten und eine Fehlermeldung darüber bereitgestellt, was schiefgelaufen ist.

Wenn eine Migration einen Bug hat, der zu einem korrupten Zustand einer Einstellung führt, ist der korrekte Weg, das Problem zu beheben, eine neue Migration zu erstellen, die den korrupten Zustand korrigiert, anstatt die ursprüngliche Migration zu ändern.


Dieses Dokument wird versionskontrolliert – schlagen Sie Änderungen auf GitHub vor.

9 „Gefällt mir“