Aggiornare EmDash

Questa guida è per gli operatori dei siti: le persone che gestiscono un sito costruito su EmDash e vogliono portarlo a una release più recente. Copre il pacchetto emdash e @emdash-cms/cloudflare. I pacchetti dei plugin hanno una propria guida, Aggiornare i plugin sul tuo sito, e le modifiche alle tue collezioni e ai tuoi campi sono trattate in Evolvere lo schema di un sito distribuito.

Release e numeri di versione

EmDash viene rilasciato prima della versione 1.0 e i suoi numeri di versione seguono due regole:

• Una release patch, ad esempio da 0.35.0 a 0.35.1, contiene correzioni di bug e piccoli miglioramenti.
• Una release minor, ad esempio da 0.35 a 0.36, contiene nuove funzionalità e qualsiasi modifica incompatibile. Una modifica incompatibile è contrassegnata come Breaking nella sua voce di release, e la voce indica l’azione che richiede da parte tua.

emdash e @emdash-cms/cloudflare vengono rilasciati insieme e condividono un unico numero di versione. @emdash-cms/cloudflare dipende dalla versione esattamente corrispondente di emdash, quindi aggiorna i due pacchetti in un solo passaggio. I pacchetti dei plugin come @emdash-cms/plugin-forms hanno propri numeri di versione e dichiarano la versione minima di emdash di cui hanno bisogno.

La pagina delle release ha una voce per pacchetto e versione. Prima di un aggiornamento, leggi le voci di emdash tra la tua versione installata e quella di destinazione, e lo stesso intervallo per @emdash-cms/cloudflare se il sito gira su Cloudflare.

I file dei template non vengono aggiornati

Creare un sito da un template copia i file del template, come layout, componenti, stili e astro.config.mjs, nel tuo progetto. Un aggiornamento modifica solo i pacchetti installati e lascia questi file così come sono. Le modifiche successive a un template si applicano solo ai nuovi siti. Per adottarne una in un sito esistente, confronta i tuoi file con la versione attuale nella directory templates e copia le modifiche che vuoi.

Prima di aggiornare

Esegui un backup ripristinabile del database e un backup separato dell’archiviazione dei media. L’esportazione JSON di EmDash non può ripristinare un sito, e le migrazioni del core non hanno un passaggio operativo di annullamento. Backup e ripristino descrive il punto di ripristino utilizzabile per ciascun database.

Controlla la versione di Node.js sulla macchina che compila il sito e, per un deployment Node.js, sul server. Crea il tuo primo sito EmDash elenca le versioni supportate.

Aggiornare i pacchetti

I comandi qui sotto usano pnpm e un sito creato da un template Cloudflare. Per un deployment Node.js, ometti @emdash-cms/cloudflare.

Distribuire e verificare

Distribuisci la build come qualsiasi altra modifica. Il comando seguente distribuisce un sito Cloudflare; per un deployment Node.js, riavvia il processo del server con la nuova build.

pnpm wrangler deploy

Con la modalità di migrazione a runtime predefinita, auto, il sito distribuito applica le migrazioni del core in sospeso alla sua prima richiesta. Per applicarle prima che il nuovo codice riceva traffico, e per verificare in seguito il database distribuito, segui Gestire le migrazioni del database core. Il suo comando emdash migrate --check termina con un codice diverso da zero quando il database distribuito ha migrazioni in sospeso o sconosciute per la versione installata.

Dopo il deploy, apri l’admin, carica almeno una pagina pubblica, modifica e pubblica una voce usa e getta, e carica e recupera un file multimediale usa e getta. Se il sito usa attività pianificate o plugin in sandbox, verifica anche quei percorsi.

Note per release specifiche

La maggior parte delle release non richiede nulla oltre ai passaggi qui sopra. Le voci seguenti riguardano le release che hanno modificato dati che EmDash aveva già memorizzato, e indicano quando ciò richiede un’azione da parte tua.

Modificato: i campi di riferimento si legano alle relation

Un campo reference conservava in passato l’ID della voce di destinazione in una colonna della tabella della sua collezione, e nominava la collezione di destinazione in un’opzione del campo che il pannello di amministrazione non poteva impostare.

Un campo di riferimento è ora un selettore di voci basato su una relazione, e i suoi collegamenti risiedono fuori dalla tabella della collezione. L’aggiornamento lega ogni campo di riferimento che nominava una collezione di destinazione a una nuova relazione e vi copia come collegamenti gli ID delle voci presenti nella sua colonna, così il campo diventa un selettore con la selezione intatta. La colonna viene lasciata al suo posto e l’aggiornamento non elimina nulla.

Un campo resta non legato quando:

• non nomina alcuna collezione di destinazione, oppure ne nomina una che non esiste più
• è contrassegnato come ricercabile o indicizzato
• richiede lo slug di relazione {collection}_{field} e quello slug è già in uso
• seleziona voci diverse in locale diversi della stessa voce, su qualsiasi voce

L’ultima condizione riguarda dove risiedono i collegamenti. Un collegamento appartiene al gruppo di traduzione di una voce, quindi una selezione è condivisa da tutte le sue traduzioni, mentre la vecchia colonna era per locale. Un campo i cui locale non concordano non ha una singola selezione da riportare — unirle darebbe a ciascun locale le voci dell’altro, e scegliere la risposta di un locale scarterebbe le altre — quindi l’aggiornamento lascia il campo com’è e entrambi i valori leggibili nella colonna.

Due casi che sembrano disaccordo non lo sono. I locale che nominano le proprie traduzioni di una stessa voce hanno selezionato quella voce una sola volta, quindi l’aggiornamento lega il campo e il collegamento si risolve nella versione propria di ciascun locale. Un locale che non ha selezionato nulla non contraddice alcun altro locale, quindi l’aggiornamento lega il campo e l’unica selezione del gruppo si applica a ogni traduzione, compresa quella vuota.

Un campo non legato continua a comportarsi come prima. La sua colonna contiene l’ID della voce, il valore viene salvato e caricato, e il campo può ancora essere indicizzato e usato come filtro dell’elenco dei contenuti. Nell’editor della voce viene mostrato come una casella di testo anziché come un selettore.

Cosa dovrei fare?

Apri una voce in ciascuna collezione che ha un campo di riferimento. Un campo mostrato come selettore non richiede nulla. Per un campo che viene ancora mostrato come casella di testo, segui Legare un campo che non ha relazione, che crea la relazione e vi copia come collegamenti gli ID memorizzati del campo. Su un sito con più locale, decidi a quale voce deve puntare ciascuna traduzione prima di legare, poiché il legame mantiene un’unica selezione per tutte.

Se il sito si rompe dopo un aggiornamento

• La build fallisce, oppure una tua pagina va in errore a runtime: leggi le voci di release contrassegnate come Breaking per le versioni che hai saltato e apporta le modifiche che indicano.
• Un plugin non si carica: leggi la voce di release del plugin stesso e Aggiornare i plugin sul tuo sito.
• Un errore nomina un’API di Astro o un pacchetto @astrojs/*: EmDash richiede Astro 6 o successivo. La guida all’aggiornamento di Astro spiega come aggiornare insieme astro e le sue integrazioni ufficiali.
• Per tornare alla release precedente, reinstalla le versioni precedenti dei pacchetti corrispondenti e distribuisci di nuovo quell’artefatto. La reinstallazione non annulla le migrazioni del core. Se l’artefatto precedente non può usare il database migrato, ferma il traffico e ripristina insieme il database precedente all’aggiornamento e l’artefatto; ripristina i media solo se l’aggiornamento li ha modificati.