EmDash aktualisieren

Dieser Leitfaden richtet sich an Site-Betreiber: Personen, die eine auf EmDash basierende Site betreiben und auf ein neueres Release umstellen möchten. Der Updater deckt jede direkte Abhängigkeit von emdash und @emdash-cms/* im Projekt ab. Änderungen an Ihren eigenen Collections und Feldern werden in Schema einer bereitgestellten Website weiterentwickeln behandelt.

Release-Kompatibilität

EmDash folgt Semantic Versioning:

• Ein Patch-Release enthält abwärtskompatible Fehlerbehebungen und kleine Verbesserungen.
• Ein Minor-Release enthält abwärtskompatible Funktionen.
• Ein Major-Release kann Änderungen an einem bestehenden Projekt erfordern. Seine Release-Einträge nennen die betroffenen Projekte und die erforderlichen Maßnahmen.

emdash und @emdash-cms/cloudflare werden gemeinsam veröffentlicht und teilen sich eine Versionsnummer. @emdash-cms/cloudflare hängt von der exakt passenden emdash-Version ab, aktualisieren Sie die beiden Pakete daher in einem Schritt. Plugin-Pakete wie @emdash-cms/plugin-forms haben eigene Versionsnummern und deklarieren die Mindestversion von emdash, die sie benötigen.

Die Releases-Seite hat einen Eintrag pro Paket und Version. upgrade-emdash ruft den Changelog-Bereich für jedes direkte Paket über dessen exaktes GitHub-Release-Tag ab. Es entfernt automatisch erzeugte Einträge für Abhängigkeits-Updates, behält die vollständigen, von Hand verfassten Major-, Minor- und Patch-Einträge bei und entfernt Einträge, die in mehreren Paketen wiederholt vorkommen.

Template-Dateien werden nicht aktualisiert

Beim Erstellen einer Site aus einem Template werden die Dateien des Templates, etwa Layouts, Komponenten, Styles und astro.config.mjs, in Ihr Projekt kopiert. Der Updater ändert direkte EmDash-Abhängigkeiten und aktualisiert die EmDash-Agent-Skills. Die Anwendungs- und Konfigurationsdateien der Site lässt er unverändert; sie ändern der Projektverantwortliche oder ein Agent anhand des Upgrade-Arbeitsauftrags. Spätere Änderungen an einem Template gelten nur für neue Sites. Um eine Änderung in einer bestehenden Site zu übernehmen, vergleichen Sie Ihre Dateien mit der aktuellen Version im templates-Verzeichnis und kopieren Sie die gewünschten Änderungen.

Bevor Sie aktualisieren

Der Updater ändert Projektdateien und installierte Pakete, ohne sich mit der Datenbank der Site zu verbinden. Daher verlangt er vor dem Start kein Backup speziell für das Upgrade. Nach der Installation nennt .emdash/UPGRADE.md alle hinzugekommenen Core-Migrationen.

Erstellen Sie vor dem Starten oder Deployen der aktualisierten Anwendung einen Wiederherstellungspunkt, wenn der Arbeitsauftrag hinzugekommene Migrationen auflistet, emdash migrate --status eine frühere ausstehende Migration meldet oder ein Release-Eintrag eine datenändernde Projektmaßnahme verlangt. Folgen Sie für die konfigurierte Datenbank Backups und Wiederherstellung. Das JSON-Backup von EmDash kann eine Site nicht wiederherstellen.

Der Updater setzt emdash 0.35.0 oder neuer voraus, das erste Release, das seine Core-Migrationen meldet. Erstellen Sie bei einer älteren Site einen Wiederherstellungspunkt, aktualisieren Sie emdash und die übrigen direkten @emdash-cms/*-Pakete mit dem Paketmanager des Projekts auf 0.35.0 und lesen Sie die Paket-Changelogs bis zu diesem Release. Führen Sie anschließend den Updater für den Rest des Updates aus.

Der Updater liest Pakete aus node_modules und unterstützt daher keine Yarn-Plug’n’Play-Installationen. Setzen Sie bei einem Yarn-Projekt mit Plug’n’Play nodeLinker: node-modules in .yarnrc.yml und führen Sie yarn install aus, bevor Sie den Updater starten.

Prüfen Sie die Node.js-Version auf dem Rechner, der die Site baut, und bei einem Node.js-Deployment auch auf dem Server. Erste EmDash-Site erstellen listet die unterstützten Versionen auf.

Das Update planen und anwenden

Führen Sie den Updater im Projektverzeichnis der Site aus. Er liest die installierten Paketversionen und die Identität der Core-Migrationen und löst dann den gewählten npm-dist-tag für jedes direkte EmDash-Paket separat auf. Der Standard-Tag ist latest; mit --to next, --to beta oder einem anderen dist-tag wählen Sie einen Release-Kanal. --to akzeptiert keine exakte Version.

Deployen und überprüfen

Deployen Sie den Build genauso wie jede andere Änderung. Der folgende Befehl deployt eine Cloudflare-Site; starten Sie bei einem Node.js-Deployment den Serverprozess mit dem neuen Build neu.

pnpm wrangler deploy

Im standardmäßigen Laufzeit-Migrationsmodus auto wendet die bereitgestellte Site ausstehende Core-Migrationen bei ihrer ersten Anfrage an. Deployen Sie keinen Build mit ausstehenden Migrationen, bevor der erforderliche Wiederherstellungspunkt existiert. Um Migrationen anzuwenden, bevor der neue Code Datenverkehr erhält, und um die bereitgestellte Datenbank anschließend zu überprüfen, folgen Sie Core-Datenbankmigrationen verwalten. Der Befehl emdash migrate --check beendet sich mit einem Wert ungleich null, wenn die bereitgestellte Datenbank ausstehende oder unbekannte Migrationen für die installierte Version hat.

Öffnen Sie nach dem Deployment den Admin, laden Sie mindestens eine öffentliche Seite, bearbeiten und veröffentlichen Sie einen Wegwerf-Eintrag und laden Sie eine Wegwerf-Mediendatei hoch und wieder ab. Verwendet die Site geplante Aufgaben oder Sandbox-Plugins, überprüfen Sie auch diese Pfade.

Hinweise für bestimmte Releases

Die meisten Releases erfordern nichts über die obigen Schritte hinaus. Die folgenden Einträge behandeln Releases, die von EmDash bereits gespeicherte Daten geändert haben, und sagen, wann das eine Maßnahme von Ihnen erfordert.

Geändert: Referenzfelder binden an Relations

Ein reference-Feld hielt früher die ID des Zieleintrags in einer Spalte der Tabelle seiner Collection und nannte seine Ziel-Collection in einer Feldoption, die das Admin-Panel nicht setzen konnte.

Ein Referenzfeld ist jetzt eine Eintragsauswahl, die auf einer Relation beruht, und seine Verknüpfungen liegen außerhalb der Collection-Tabelle. Das Update bindet jedes Referenzfeld, das eine Ziel-Collection genannt hat, an eine neue Relation und kopiert die Eintrags-IDs aus seiner Spalte als Verknüpfungen hinein, sodass das Feld zu einer Auswahl mit unveränderter Auswahl wird. Die Spalte bleibt bestehen, und das Update löscht nichts.

Ein Feld bleibt ungebunden, wenn es:

• keine Ziel-Collection nennt oder eine nennt, die nicht mehr existiert
• als durchsuchbar oder indiziert markiert ist
• den Relation-Slug {collection}_{field} benötigt und dieser Slug bereits vergeben ist
• in verschiedenen Locales desselben Eintrags unterschiedliche Einträge auswählt, bei einem beliebigen Eintrag

Der letzte Punkt betrifft den Ort, an dem Verknüpfungen liegen. Eine Verknüpfung gehört zur Übersetzungsgruppe eines Eintrags, sodass eine Auswahl von allen seinen Übersetzungen geteilt wird, während die alte Spalte pro Locale galt. Ein Feld, dessen Locales voneinander abweichen, hat keine einzelne Auswahl, die übernommen werden kann — sie zusammenzuführen würde jeder Locale die Einträge der anderen geben, und die Antwort einer Locale auszuwählen würde den Rest verwerfen —, daher lässt das Update das Feld unverändert und beide Werte in der Spalte lesbar.

Zwei Fälle, die wie Abweichungen aussehen, sind keine. Locales, die für einen Eintrag ihre eigenen Übersetzungen nennen, haben diesen Eintrag einmal ausgewählt, daher bindet das Update das Feld, und die Verknüpfung wird zur jeweils eigenen Version jeder Locale aufgelöst. Eine Locale, die nichts ausgewählt hat, widerspricht keiner anderen Locale, daher bindet das Update das Feld, und die eine Auswahl der Gruppe gilt für jede Übersetzung, auch für die leere.

Ein ungebundenes Feld verhält sich weiterhin wie bisher. Seine Spalte enthält die Eintrags-ID, der Wert wird gespeichert und geladen, und das Feld kann weiterhin indiziert und als Filter der Inhaltsliste verwendet werden. Im Eintragseditor wird es als Textfeld statt als Auswahl dargestellt.

Was soll ich tun?

Öffnen Sie in jeder Collection mit einem Referenzfeld einen Eintrag. Ein Feld, das als Auswahl dargestellt wird, braucht nichts. Für ein Feld, das weiterhin als Textfeld dargestellt wird, folgen Sie Ein Feld ohne Relation binden, das die Relation erstellt und die gespeicherten IDs des Felds als Verknüpfungen hineinkopiert. Legen Sie bei einer Site mit mehreren Locales vor dem Binden fest, auf welchen Eintrag jede Übersetzung zeigen soll, da das Binden eine Auswahl für alle beibehält.

Wenn die Site nach einem Update bricht

• Der Build schlägt fehl, oder eine eigene Seite verursacht zur Laufzeit einen Fehler: Lesen Sie die mit Breaking gekennzeichneten Release-Einträge der übersprungenen Versionen und nehmen Sie die dort genannten Änderungen vor.
• Ein Plugin lässt sich nicht laden: Lesen Sie den eigenen Release-Eintrag des Plugins und Plugins auf Ihrer Site aktualisieren.
• Ein Fehler nennt eine Astro-API oder ein @astrojs/*-Paket: EmDash benötigt Astro 6 oder höher. Der Upgrade-Leitfaden von Astro erklärt, wie Sie astro und seine offiziellen Integrationen gemeinsam aktualisieren.
• Um zum vorherigen Release zurückzukehren, installieren Sie die passenden vorherigen Paketversionen neu und deployen Sie dieses Artefakt erneut. Eine Neuinstallation macht Core-Migrationen nicht rückgängig. Kann das vorherige Artefakt die migrierte Datenbank nicht verwenden, stoppen Sie den Datenverkehr und stellen Sie die Datenbank vor dem Update und das Artefakt gemeinsam wieder her; stellen Sie Medien nur wieder her, wenn das Update sie geändert hat.