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. El actualizador cubre todas las dependencias directas de emdash y @emdash-cms/* del proyecto. Los cambios en tus propias colecciones y campos se tratan en Evolucionar el esquema de un sitio desplegado.

Compatibilidad entre releases

EmDash sigue el versionado semántico:

• Un release de parche incluye correcciones y pequeñas mejoras compatibles con versiones anteriores.
• Un release menor incluye funciones compatibles con versiones anteriores.
• Un release mayor puede exigir cambios en un proyecto existente. Sus entradas de release identifican los proyectos afectados y las acciones necesarias.

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. upgrade-emdash obtiene el rango del changelog de cada paquete directo a partir de su etiqueta exacta de release de GitHub. Elimina las entradas generadas de actualización de dependencias, conserva íntegras las entradas mayores, menores y de parche redactadas a mano, y elimina las entradas repetidas entre paquetes.

Los archivos de plantilla no se actualizan

Al crear un sitio a partir de una plantilla se copian a tu proyecto los archivos de la plantilla, como layouts, componentes, estilos y astro.config.mjs. El actualizador modifica las dependencias directas de EmDash y refresca las agent skills de EmDash. Deja los archivos de aplicación y de configuración del sitio para que el responsable del proyecto o un agente los cambie a partir de la orden de trabajo de la actualizació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

El actualizador modifica archivos del proyecto y paquetes instalados sin conectarse a la base de datos del sitio, por lo que no exige una copia de seguridad específica para la actualización antes de ejecutarse. Tras la instalación, .emdash/UPGRADE.md identifica las migraciones del núcleo añadidas, si las hay.

Antes de iniciar o desplegar la aplicación actualizada, crea un punto de recuperación cuando la orden de trabajo enumere migraciones añadidas, emdash migrate --status informe de una migración pendiente anterior o una entrada de release exija una acción del proyecto que modifique datos. Sigue Copias de seguridad y recuperación para la base de datos configurada. La copia JSON de EmDash no puede restaurar un sitio.

El actualizador requiere emdash 0.35.0 o posterior, el primer release que informa de sus migraciones del núcleo. Para un sitio más antiguo, crea un punto de recuperación, actualiza emdash y los demás paquetes directos @emdash-cms/* a 0.35.0 con el gestor de paquetes del proyecto y revisa los changelogs de los paquetes hasta ese release. Después ejecuta el actualizador para el resto de la actualización.

El actualizador lee los paquetes desde node_modules, así que no admite instalaciones de Yarn Plug’n’Play. En un proyecto de Yarn que use Plug’n’Play, establece nodeLinker: node-modules en .yarnrc.yml y ejecuta yarn install antes de ejecutar el actualizador.

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 admitidas.

Planificar y aplicar la actualización

Ejecuta el actualizador desde el directorio del proyecto del sitio. Lee las versiones de los paquetes instalados y la identidad de las migraciones del núcleo, y luego resuelve la dist-tag de npm seleccionada por separado para cada paquete directo de EmDash. La etiqueta predeterminada es latest; usa --to next, --to beta u otra dist-tag para elegir un canal de releases. --to no acepta una versión exacta.

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. Un Worker de Cloudflare deja las migraciones de contenido grandes a emdash migrate y responde con 503 hasta que se aplican. No despliegues una compilación con migraciones pendientes hasta que exista el punto de recuperación necesario. Para aplicar las migraciones 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 cambian datos que EmDash ya tenía almacenados, o que no pueden repararlos, 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.

Corregido: campos de referencia con búsqueda

En versiones anteriores, un campo de referencia marcado como searchable rompía su colección: añadir uno a una colección con la búsqueda activada fallaba, y después de que un seed activara la búsqueda, crear o guardar cualquier entrada de esa colección fallaba con no such column en el registro del servidor.

La búsqueda del sitio y la búsqueda de la lista de contenido ignoran la marca searchable en un campo de referencia vinculado a una relation. Actualizar no repara una colección que un seed ya haya roto, porque su índice de búsqueda sigue esperando el campo.

¿Qué debo hacer?

Si crear o guardar entradas en una colección falla y el registro del servidor muestra no such column, abre la colección en Content Types, desmarca la casilla Search y guarda. Luego vuelve a marcar Search y guarda. Esto reconstruye el índice de búsqueda de la colección, y la colección vuelve a aceptar entradas nuevas y editadas.

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ó.