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. L’updater copre ogni dipendenza diretta emdash e @emdash-cms/* del progetto. Le modifiche alle tue collezioni e ai tuoi campi sono trattate in Evolvere lo schema di un sito distribuito.

Compatibilità delle release

EmDash segue il versionamento semantico:

• Una release patch contiene correzioni e piccoli miglioramenti retrocompatibili.
• Una release minor contiene funzionalità retrocompatibili.
• Una release major può richiedere modifiche a un progetto esistente. Le sue voci di release identificano i progetti interessati e le azioni necessarie.

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. upgrade-emdash recupera l’intervallo del changelog di ogni pacchetto diretto dal suo tag di release GitHub esatto. Rimuove le voci generate di aggiornamento delle dipendenze, conserva per intero le voci major, minor e patch scritte a mano ed elimina i duplicati delle voci ripetute tra più pacchetti.

I file dei template non vengono aggiornati

Creare un sito da un template copia nel tuo progetto i file del template, come layout, componenti, stili e astro.config.mjs. L’updater modifica le dipendenze dirette di EmDash e aggiorna le agent skill di EmDash. Lascia i file dell’applicazione e di configurazione del sito al responsabile del progetto o a un agente, che li modificano in base all’ordine di lavoro dell’aggiornamento. 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

L’updater modifica i file del progetto e i pacchetti installati senza connettersi al database del sito, quindi non richiede un backup specifico per l’aggiornamento prima di essere eseguito. Dopo l’installazione, .emdash/UPGRADE.md indica le eventuali migrazioni del core aggiunte.

Prima di avviare o distribuire l’applicazione aggiornata, crea un punto di ripristino quando l’ordine di lavoro elenca migrazioni aggiunte, emdash migrate --status segnala una migrazione precedente in sospeso o una voce di release richiede un’azione di progetto che modifica i dati. Segui Backup e ripristino per il database configurato. Il backup JSON di EmDash non può ripristinare un sito.

L’updater richiede emdash 0.35.0 o successivo, la prima release che segnala le proprie migrazioni del core. Per un sito più vecchio, crea un punto di ripristino, aggiorna emdash e gli altri pacchetti diretti @emdash-cms/* alla 0.35.0 con il gestore di pacchetti del progetto e rivedi i changelog dei pacchetti fino a quella release. Poi esegui l’updater per il resto dell’aggiornamento.

L’updater legge i pacchetti da node_modules, quindi non supporta le installazioni Yarn Plug’n’Play. Per un progetto Yarn che usa Plug’n’Play, imposta nodeLinker: node-modules in .yarnrc.yml ed esegui yarn install prima di eseguire l’updater.

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

Pianificare e applicare l’aggiornamento

Esegui l’updater dalla directory del progetto del sito. Legge le versioni dei pacchetti installati e l’identità delle migrazioni del core, poi risolve separatamente il dist-tag npm selezionato per ogni pacchetto EmDash diretto. Il tag predefinito è latest; usa --to next, --to beta o un altro dist-tag per selezionare un canale di release. --to non accetta una versione esatta.

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. Un Worker Cloudflare lascia le migrazioni di contenuti di grandi dimensioni a emdash migrate e risponde con 503 finché non vengono applicate. Non distribuire una build con migrazioni in sospeso finché non esiste il punto di ripristino richiesto. Per applicare le migrazioni 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 modificano dati che EmDash aveva già memorizzato, o che non possono ripararli, 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.

Corretto: campi di riferimento ricercabili

Nelle versioni precedenti, un campo di riferimento contrassegnato come searchable rompeva la propria collezione: aggiungerne uno a una collezione con la ricerca attivata falliva e, dopo che un seed aveva attivato la ricerca, creare o salvare qualsiasi voce di quella collezione falliva con no such column nel log del server.

La ricerca del sito e la ricerca nell’elenco dei contenuti ignorano il flag searchable su un campo di riferimento legato a una relation. L’aggiornamento non ripara una collezione già rotta da un seed, perché il suo indice di ricerca si aspetta ancora il campo.

Cosa dovrei fare?

Se creare o salvare voci in una collezione fallisce e il log del server mostra no such column, apri la collezione in Content Types, deseleziona la casella Search e salva. Poi seleziona di nuovo Search e salva. Questo ricostruisce l’indice di ricerca della collezione, e la collezione accetta di nuovo voci nuove e modificate.

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.