Actualizando Astro

Esta guía cubre como actualizar tu versión de Astro y las dependencias relacionadas, cómo aprender qué ha cambiado de una versión a otra y cómo entender el sistema de versiones de Astro y sus correspondientes actualizaciones de documentación.

¿Qué ha cambiado?

La última versión de Astro es v4.16.13

Puedes encontrar una lista detallada de todos los cambios en el historial de cambios de Astro e instrucciones importantes para actualizar a cada nueva versión mayor en nuestras guías de actualización.

Actualizar a la última versión

Actualiza la versión de Astro en tu proyecto y todas las dependencias oficiales a la última versión con un comando, usando tu gestor de paquetes.

# Actualizando Astro y las integraciones oficiales juntas
npx @astrojs/upgrade

# Actualizando Astro y las integraciones oficiales juntas
pnpm dlx @astrojs/upgrade

# Actualizando Astro y las integraciones oficiales juntas
yarn dlx @astrojs/upgrade

Actualización Manual

Para actualizar Astro y sus dependencias a sus últimas versiones manualmente, usa el comando adecuado en tu gestor de paquetes.

# Ejemplo: actualiza Astro con las integraciones de React y Tailwind
npm install astro@latest @astrojs/react@latest @astrojs/tailwind@latest

# Ejemplo: actualiza Astro con las integraciones de React y Tailwind
pnpm add astro@latest @astrojs/react@latest @astrojs/tailwind@latest

# Ejemplo: actualiza Astro con las integraciones de React y Tailwind
yarn add astro@latest @astrojs/react@latest @astrojs/tailwind@latest

Instalar una versión específica

Para instalar una versión específica de Astro o integraciones, usa el comando apropiado en tu administrador de paquetes.

npm install astro@4.5.3 @astrojs/react@3.0.10

pnpm add astro@4.5.3 @astrojs/react@3.0.10

yarn add astro@4.5.3 @astrojs/react@3.0.10

Actualización de documentación

Esta documentación está actualizada por cada versión menor y versión mayor. Cuando nuevas características son añadidas, o cambios existentes son hechos, la documentación se actualizará para reflejar el comportamiento actual de Astro. Si tu proyecto no está actualizado, podrías ver algunas funcionalidades que no corresponden con la documentación actualizada.

Nuevas características son agregadas a la documentación con la versión específica donde fueron agregados. Esto significa que si no te has actualizado a la última versión de Astro, algunas características no documentadas podrían estar no disponibles. Siempre comprueba la versión en la sección Agregado en: y asegúrate de que tu proyecto esté actualizado antes de intentar usar una nuevas características!

Si aún no te has actualizado a la última versión mayor de Astro, puedes encontrar diferencias significativas entre la documentación de Astro y el funcionamiento de tu proyecto. Recomendamos actualizar a la última versión mayor de Astro tan pronto puedas. No está disponible el código y la documentación para versiones antiguas.

Guías de actualización

Cada lanzamiento de una versión mayor, encontrarás una guía de actualización con información de los cambios importantes e instrucciones para actualizar el código de tu proyecto.

La documentación principal de Astro está siempre corregida para la última versión de Astro. No describe o compara cómo las características funcionan en versiones anteriores, ni para comparar las funcionalidades actualizadas o cambiadas.

Lee las guías de actualización a continuación para una explicación de cambios, comparando la versión nueva con la antigua. Las guías de actualización incluyen todo lo que podrías necesitar para cambiar tu propio código: cambios importantes, características obsoletas, eliminación de características y reemplazos, también como guías de uso actualizadas. Cada cambio en Astro incluye una sección “¿Qué debo hacer?” para ayudarte a actualizar el código de tu proyecto.

Documentación antigua (sin mantenimiento)

La documentación para las versiones antiguas de Astro no es mantenida, pero está disponible como referencia. Usa las versiones de la documentación siguientes si no puedes actualizar tu proyecto, pero aún así, consulta las guías y referencias:

Versionado semántico

Astro intenta seguir tanto como pueda un versionado semántico, el cuál es un grupo de reglas de desarrollo usados para determinar cómo asignar una versión numérica a un lanzamiento. El versionado semántico sigue un patrón predecible para informar a los usuarios el tipo de cambios que pueden esperar de una versión a la otra.

El versionado semántico refuerza la idea de usar X.Y.Z para numerar versiones de software. Estos valores representan lo siguiente: mayor (X), menor (Y) y actualizaciones de parche (Z).

Cambios de parche

Los cambios de parche son los cambios menos disruptivos. No cambian la manera en cómo Astro funciona y no cambian el código de tu proyecto cuando actualizas.

Cuando Astro lanza una versión de “parche”, el último número se incrementa. (Ejemplo: astro@4.3.13 -> astro@4.3.15)

Los parches pueden ser lanzados por razones como:

Cambios internos que no cambian la funcionalidad principal de Astro:
- Refactorización de código
- Mejora de rendimiento
- Aumento o cambio en el coverage de pruebas
- Sincronización entre la documentación actual y el funcionamiento esperado
Mejoras a los mensajes de error y logs.
Relanzamientos después de un error en el lanzamiento anterior.

Los parches incluyen también la mayoría de correciones de errores, incluso en casos donde los usuarios abusaban de un comportamiento no deseado.

Cambios menores

Los cambios menores principalmente introducen nuevas características y mejoras que podrías probar, pero sin cambios en tu código. Algunas características existentes podrían ser obsoletas (marcadas para eliminación en una versión futura mientras aún están disponibles en la versión actual) en una versión menor, dándote la oportunidad de prepararlas para una eliminación eventual.

Las versiones menores incluyen cambios como:

Características/Opciones obsoletas con una alerta de que serán eliminadas en una versión mayor.
Introducción de nuevas funcionalidades.
Introducción de nuevas opciones en los hooks de integración.
Introducción de nuevas funcionalidades en astro/app, notablemente usado para crear nuevos adaptadores.

Una versión menor puede incluir pequeños, cambios en parches al mismo tiempo.

Cambios mayores

Los cambios mayores incluyen cambios disruptivos que pueden afectar el código existente. Estos cambios importantes son siempre documentados en una guía de “Actualizar a vX” en Astro.

Las versiones mayores también incluyen cambios significativos no sólo a la lógica interna, pero también al comportamiento esperado y uso. La documentación será actualizada para reflejar sólo la última versión y las versiones antiguas de la documentación antigua estarán disponibles como registro histórico para proyectos antiguos que no se hayan actualizado.

Los cambios mayores incluyen cambios como:

Eliminación de funcionalidades marcadas como obsoletas en una versión anterior.
Cambios a funcionalidades existentes.
Cambios a opciones existentes en los hooks de integración.
Cambios en las opciones existentes y funcionalidades dentro de astro/app, notablemente usado para crear nuevos adaptadores.

Un lanzamiento mayor puede también incluir algunos cambios no disruptivos y mejoras que serían normalmente lanzadas separadamente en una versión menor o una versión de parche.

Excepciones

Cambios experimentales. Versiones lanzadas de Astro que no se adhieran al versionado semántico permite a los desarrolladores de Astro la más grande flexibilidad para experimentar, y radicalmente cambiar el curso, durante el desarrollo de funcionalidades experimentales. Por lo tanto, el comportamiento de estas características podría no funcionar en cambios menores o de parche.

Estas características están usualmente acompañadas por un continuo, y público Request for Consideration (RFC) - Solicitud en Consideración, de etapa 3. Es esperado que los usuarios de beta puedan probar estas características y dejar comentarios en adelantado para ayudar al desarrollo de esas características.

Una vez que esas características son lanzadas fueran del período de experimentación, serán lanzadas siguiendo el versionado semántico normal.
Mejoras a la documentación (Ejemplo: referencias y mensajes de error). Son tomadas desde la carpeta docs del repositorio. Esto permite a astro a actualizar la documentación rápidamente con arreglos y mejoras en los casos donde la fuente de la documentación es almacenada en el repositorio de Astro principal.

Soporte para Node.js y políticas de actualización

Soporte

Astro soporta la última versión LTS en mantenimiento de Node.js.
Astro soporta la versión Activa LTS de Node.js.
Astro can support odd versions of Node.js.
Astro puede soportar versiones impares de Node.js

Actualización

Las siguientes reglas establecen cómo y cuándo Astro puede depreciar, eliminar o añadir soporte para versiones de Node.js:

Las versiones impares de Node.js pueden ser deprecadas y/o eliminadas cuando se publique la siguiente versión par de Node.js. Este cambio puede ocurrir en una versión menor de Astro, después de un período razonable de soporte extendido según lo decida el equipo principal de Astro.
Actualizar la versión mínima de Mantenimiento LTS (dentro del mismo rango mayor, por ejemplo, de v18.14.* a v18.20.*) de Node.js puede ocurrir en una versión menor de Astro.
- Excepción de seguridad: Si se revela y corrige un fallo de seguridad en Node.js que afecta a Astro, el equipo central puede aumentar la versión mínima de la versión de mantenimiento LTS en una versión de parche.
Actualizar versiones menores o mayores de Node.js (no la versión de mantenimiento LTS) sólo ocurre en versiones mayores de Astro.
- Excepción de seguridad: Si se revela y corrige un fallo de seguridad en Node.js que afecta a Astro, el equipo principal puede aumentar la versión mínima en una versión menor.

Mantenimiento extendido

El equipo principal proporcionará mantenimiento extendido sólo para correcciones de seguridad para una versión mayor anterior. Esto significa que si la versión mayor actual es v4.*, el equipo principal trasladará las correcciones de seguridad y emitirá una nueva versión v3.*.

Contribuir

Comunidad