Aggiornare EmDash

Questa guida è per gli operatori del sito: persone che gestiscono un sito basato su EmDash e vogliono portarlo a una release più recente. Copre il pacchetto emdash e @emdash-cms/cloudflare. I pacchetti di plugin hanno una propria guida, Aggiornare i plugin sul tuo sito, e le modifiche alle tue collection e ai campi sono coperte in Evolvere un sito in produzione.

Release e numeri di versione

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

• Una release di patch, ad esempio da 0.35.0 a 0.35.1, porta correzioni di bug e piccoli miglioramenti.
• Una release minore, ad esempio da 0.35 a 0.36, porta nuove funzionalità e qualsiasi breaking change. Un breaking change è contrassegnato Breaking nella sua voce di release, e la voce indica l’azione che richiede da te.

emdash e @emdash-cms/cloudflare vengono rilasciati insieme e condividono un numero di versione. @emdash-cms/cloudflare dipende dalla versione esatta corrispondente di emdash, quindi aggiorna i due pacchetti in un unico passaggio. I pacchetti di plugin come @emdash-cms/plugin-forms hanno i 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 emdash tra la versione installata e l’obiettivo, e lo stesso intervallo per @emdash-cms/cloudflare se il sito gira su Cloudflare.

Prima di aggiornare

Esegui un backup del database ripristinabile e un backup separato dello storage dei media. L’export 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 ogni database.

Controlla la versione di Node.js sulla macchina che costruisce il sito e, per un deployment Node.js, sul server. Per iniziare elenca le versioni supportate.

Aggiornare i pacchetti

I comandi seguenti 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 runtime predefinita, auto, il sito in produzione applica le migrazioni del core in sospeso alla prima richiesta. Per applicarle prima che il nuovo codice riceva traffico, e per verificare il database in produzione dopo, segui Gestire le migrazioni del database del core. Il suo comando emdash migrate --check termina con codice diverso da zero quando il database in produzione 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 media usa e getta. Se il sito usa attività pianificate o plugin sandboxed, verifica anche quei percorsi.

Note per release specifiche

La maggior parte delle release non richiede nulla oltre i passaggi sopra. Le voci seguenti coprono le release che hanno modificato dati che EmDash memorizzava già e indicano quando ciò richiede un’azione da parte tua.

Modificato: i campi di riferimento si legano alle relation

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

Un campo di riferimento è ora un selettore di voci supportato da una relation, e i suoi collegamenti vivono fuori dalla tabella della collection. L’aggiornamento lega ogni campo di riferimento che nominava una collection di destinazione a una nuova relation e copia gli ID delle voci nella sua colonna come collegamenti, così il campo diventa un selettore con la selezione intatta. La colonna resta al suo posto e l’aggiornamento non elimina nulla.

Un campo resta non legato quando:

• non nomina una collection di destinazione, o ne nomina una che non esiste più
• è contrassegnato searchable o indexed
• richiede lo slug di relation {collection}_{field} e quello slug è già occupato
• seleziona voci diverse in locale diverse della stessa voce, su qualsiasi voce

Quest’ultimo punto riguarda dove vivono 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 sono in disaccordo non ha una sola selezione da portare — unirli darebbe a ogni locale le voci dell’altro, e scegliere la risposta di un locale scarterebbe il resto — quindi l’aggiornamento lascia il campo in pace e entrambi i valori leggibili nella colonna.

Due casi che sembrano disaccordo non lo sono. Locale che nominano le proprie traduzioni di una voce hanno selezionato quella voce una volta, quindi l’aggiornamento lega il campo e il collegamento si risolve alla propria versione di ogni locale. Un locale che non ha selezionato nulla non contraddice nessun altro locale, quindi l’aggiornamento lega il campo e l’unica selezione del gruppo si applica a ogni traduzione, inclusa 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 contenuti. Nell’editor della voce si renderizza come una casella di testo anziché come un selettore.

Cosa dovrei fare?

Apri una voce in ogni collection che ha un campo di riferimento. Un campo che si renderizza come selettore non richiede nulla. Per un campo che si renderizza ancora come casella di testo, segui Legare un campo che non ha una relation, che crea la relation e copia gli ID memorizzati del campo come collegamenti. Su un sito multi-locale, stabilisci a quale voce ogni traduzione dovrebbe puntare prima di legare, poiché il legame mantiene una selezione per tutte.

Se il sito si rompe dopo un aggiornamento

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