Actualizar EmDash

Esta guía es para operadores de sitios: personas que gestionan un sitio construido sobre 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 tratan en Evolucionar el esquema de 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, incluye correcciones de errores y pequeñas mejoras.
• Un release menor, por ejemplo de 0.35 a 0.36, incluye nuevas funciones y cualquier cambio incompatible. Un cambio incompatible se marca como Breaking en su entrada de release, y la entrada indica la acción que requiere de ti.

emdash y @emdash-cms/cloudflare se publican juntos y comparten un único número de versión. @emdash-cms/cloudflare depende de la versión exacta de emdash que coincide, 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 actualizar, lee las entradas de emdash entre tu versión instalada y la de destino, y el mismo rango para @emdash-cms/cloudflare si el sitio se ejecuta en Cloudflare.

Los archivos de plantilla no se actualizan

Crear un sitio a partir de una plantilla copia los archivos de la plantilla, como layouts, componentes, estilos y astro.config.mjs, en tu proyecto. Una actualización solo cambia los paquetes instalados y deja estos archivos como están. Los cambios posteriores en una plantilla se aplican solo a los sitios nuevos. Para adoptar uno en un sitio existente, compara tus archivos con la versión actual del directorio templates y copia los cambios que quieras.

Antes de actualizar

Haz una copia de seguridad restaurable de la base de datos y una copia de seguridad independiente 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 utilizable para cada base de datos.

Comprueba la versión de Node.js en la máquina que construye el sitio y, en un despliegue con Node.js, en el servidor. Crear tu primer sitio EmDash enumera las versiones compatibles.

Actualizar los paquetes

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

Desplegar y verificar

Despliega la compilación igual que cualquier otro cambio. El siguiente comando despliega un sitio de Cloudflare; en un despliegue con 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 nuevo código reciba tráfico, y para verificar después la base de datos desplegada, sigue Gestionar migraciones de base de datos del núcleo. Su comando emdash migrate --check termina con un 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 multimedia desechable. Si el sitio usa tareas programadas o plugins en sandbox, 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 de abajo cubren los releases que cambiaron datos que EmDash ya tenía almacenados, e indican cuándo eso requiere una acción por tu parte.

Cambiado: los campos de referencia se vinculan a relations

Un campo reference guardaba antes 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 relación, 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 relación y copia como vínculos los IDs de entrada de su columna, 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 se deja sin vincular cuando:

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

Esa última condición tiene que ver con dónde viven los vínculos. Un vínculo pertenece al grupo de traducción de una entrada, así que una selección es compartida por todas sus traducciones, mientras que la columna antigua era por locale. Un campo cuyos locales discrepan no tiene una única selección que trasladar —combinarlas daría a cada locale las entradas del otro, y elegir la respuesta de un locale descartaría el resto—, de modo que la actualización deja el campo como está y ambos valores legibles en la columna.

Dos casos que parecen discrepancia no lo son. Los locales que nombran sus propias traducciones de una misma entrada han seleccionado esa entrada una sola vez, así que la actualización vincula el campo y el vínculo se resuelve a la versión propia 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 todas las traducciones, incluida la vacía.

Un campo sin vincular sigue comportándose como antes. Su columna contiene el ID de la entrada, el valor se guarda y se carga, y el campo todavía puede indexarse y usarse como filtro de la lista de contenido. En el editor de entradas se muestra 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 muestra como selector no necesita nada. Para un campo que todavía se muestra como cuadro de texto, sigue Vincular un campo que no tiene relación, que crea la relación y copia como vínculos los IDs almacenados del campo. En un sitio con varios locales, decide a qué entrada debe apuntar cada traducción antes de vincular, ya que vincular conserva una única selección para todas.

Si el sitio se rompe tras una actualización

• La compilación falla, o una página tuya da error en tiempo de ejecución: lee las entradas de release marcadas como Breaking de las versiones que te saltaste y haz los cambios que indican.
• Un plugin no se carga: lee la entrada de release del propio 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 anteriores de los paquetes correspondientes 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 previa a la actualización y el artefacto; restaura los medios solo si la actualización los cambió.