Actualizar EmDash

Esta guía es para operadores del sitio: personas que ejecutan un sitio basado en EmDash y quieren llevarlo a una versión más reciente. Cubre el paquete emdash y @emdash-cms/cloudflare. Los paquetes de plugins tienen su propia guía, Actualizar plugins en tu sitio, y los cambios en tus propias colecciones y campos se cubren en Evolucionar un sitio desplegado.

Releases y números de versión

EmDash se publica antes de la versión 1.0, y sus números de versión siguen dos reglas:

• Un release de parche, por ejemplo de 0.35.0 a 0.35.1, lleva correcciones de errores y pequeñas mejoras.
• Un release menor, por ejemplo de 0.35 a 0.36, lleva nuevas funciones y cualquier cambio disruptivo. Un cambio disruptivo se marca Breaking en su entrada de release, y la entrada indica la acción que te exige.

emdash y @emdash-cms/cloudflare se publican juntos y comparten un número de versión. @emdash-cms/cloudflare depende de la versión exacta coincidente de emdash, así que actualiza los dos paquetes en un solo paso. Los paquetes de plugins como @emdash-cms/plugin-forms tienen sus propios números de versión y declaran la versión mínima de emdash que necesitan.

La página de releases tiene una entrada por paquete y versión. Antes de una actualización, lee las entradas de emdash entre tu versión instalada y la objetivo, y el mismo rango para @emdash-cms/cloudflare si el sitio se ejecuta en Cloudflare.

Antes de actualizar

Haz una copia de seguridad restaurable de la base de datos y una copia de seguridad separada del almacenamiento de medios. La exportación JSON de EmDash no puede restaurar un sitio, y las migraciones del núcleo no tienen un paso operativo de deshacer. Copias de seguridad y recuperación describe el punto de recuperación usable para cada base de datos.

Comprueba la versión de Node.js en la máquina que construye el sitio y, para un despliegue Node.js, en el servidor. Primeros pasos enumera las versiones admitidas.

Actualizar los paquetes

Los comandos siguientes usan pnpm y un sitio creado a partir de una plantilla de Cloudflare. Para un despliegue Node.js, omite @emdash-cms/cloudflare.

Desplegar y verificar

Despliega la compilación igual que cualquier otro cambio. El siguiente comando despliega un sitio Cloudflare; para un despliegue Node.js, reinicia el proceso del servidor con la nueva compilación.

pnpm wrangler deploy

Con el modo de migración en tiempo de ejecución predeterminado, auto, el sitio desplegado aplica las migraciones del núcleo pendientes en su primera petición. Para aplicarlas antes de que el código nuevo reciba tráfico, y para verificar la base de datos desplegada después, sigue Gestionar migraciones de la base de datos del núcleo. Su comando emdash migrate --check termina con código distinto de cero cuando la base de datos desplegada tiene migraciones pendientes o desconocidas para la versión instalada.

Tras el despliegue, abre el admin, carga al menos una página pública, edita y publica una entrada desechable, y sube y recupera un archivo de medios desechable. Si el sitio usa tareas programadas o plugins sandboxed, verifica también esas rutas.

Notas para releases concretos

La mayoría de los releases no necesitan nada más allá de los pasos anteriores. Las entradas siguientes cubren releases que cambiaron datos que EmDash ya almacenaba, e indican cuándo eso requiere una acción tuya.

Cambiado: los campos de referencia se vinculan a relations

Un campo reference solía guardar el ID de la entrada de destino en una columna de la tabla de su colección, y nombraba su colección de destino en una opción de campo que el panel de administración no podía establecer.

Un campo de referencia es ahora un selector de entradas respaldado por una relation, y sus vínculos viven fuera de la tabla de la colección. La actualización vincula cada campo de referencia que nombraba una colección de destino a una nueva relation y copia los ID de entrada de su columna como vínculos, de modo que el campo se convierte en un selector con su selección intacta. La columna se deja en su sitio y la actualización no elimina nada.

Un campo queda sin vincular cuando:

• no nombra una colección de destino, o nombra una que ya no existe
• está marcado como searchable o indexed
• necesita el slug de relation {collection}_{field} y ese slug ya está ocupado
• selecciona entradas distintas en distintos locales de la misma entrada, en cualquier entrada

Eso último tiene que ver con dónde viven los vínculos. Un vínculo pertenece al grupo de traducción de una entrada, de modo que una selección se comparte entre todas sus traducciones, mientras que la columna antigua era por locale. Un campo cuyos locales discrepan no tiene una sola selección que trasladar — fusionarlos daría a cada locale las entradas del otro, y elegir la respuesta de un locale descartaría el resto — así que la actualización deja el campo en paz y ambos valores legibles en la columna.

Dos casos que parecen discrepancia no lo son. Locales que nombran sus propias traducciones de una entrada han seleccionado esa entrada una vez, así que la actualización vincula el campo y el vínculo se resuelve a la propia versión de cada locale. Un locale que no seleccionó nada no contradice a ningún otro locale, así que la actualización vincula el campo y la única selección del grupo se aplica a cada traducción, incluida la vacía.

Un campo sin vincular sigue comportándose como antes. Su columna guarda el ID de la entrada, el valor se guarda y se carga, y el campo aún puede indexarse y usarse como filtro de lista de contenido. En el editor de entradas se renderiza como un cuadro de texto en lugar de un selector.

¿Qué debo hacer?

Abre una entrada en cada colección que tenga un campo de referencia. Un campo que se renderiza como selector no necesita nada. Para un campo que aún se renderiza como cuadro de texto, sigue Vincular un campo que no tiene relation, que crea la relation y copia los ID almacenados del campo como vínculos. En un sitio multi-locale, decide a qué entrada debe apuntar cada traducción antes de vincular, ya que vincular mantiene una selección para todas ellas.

Si el sitio se rompe tras una actualización

• La compilación falla, o una página tuya falla en tiempo de ejecución: lee las entradas de release marcadas Breaking de las versiones que te saltaste y haz los cambios que indiquen.
• Un plugin no carga: lee la propia entrada de release del plugin y Actualizar plugins en tu sitio.
• Un error nombra una API de Astro o un paquete @astrojs/*: EmDash requiere Astro 6 o posterior. La guía de actualización de Astro explica cómo actualizar astro y sus integraciones oficiales juntos.
• Para volver al release anterior, reinstala las versiones de paquete anteriores coincidentes y vuelve a desplegar ese artefacto. Reinstalar no deshace las migraciones del núcleo. Si el artefacto anterior no puede usar la base de datos migrada, detén el tráfico y restaura juntos la base de datos y el artefacto previos a la actualización; restaura los medios solo si la actualización los cambió.