Atualize o Astro

Este guia aborda como atualizar sua versão do Astro e as dependências relacionadas, como saber o que mudou de uma versão para outra e como entender o sistema de controle de versão do Astro e as atualizações de documentação correspondentes.

O que mudou?

A versão mais recente do Astro é a v5.0.9.

Você pode encontrar uma lista exaustiva de todas as alterações no changelog do Astro e instruções importantes para atualizar para cada nova versão major em nossos guias de atualização.

Atualize para a versão mais recente

Atualize a versão do Astro do seu projeto e todas as integrações oficiais para as versões mais recentes com um comando usando seu gerenciador de pacotes:

# Atualize o Astro e as integrações oficiais juntos
npx @astrojs/upgrade

# Atualize o Astro e as integrações oficiais juntos
pnpm dlx @astrojs/upgrade

# Atualize o Astro e as integrações oficiais juntos
yarn dlx @astrojs/upgrade

Atualização manual

Para atualizar manualmente o Astro e as integrações para suas versões atuais, use o comando apropriado para seu gerenciador de pacotes.

# Exemplo: atualizar o Astro com as integrações React e Tailwind
npm install astro@latest @astrojs/react@latest @astrojs/tailwind@latest

# Exemplo: atualizar o Astro com as integrações React e Tailwind
pnpm add astro@latest @astrojs/react@latest @astrojs/tailwind@latest

# Exemplo: atualizar o Astro com as integrações React e Tailwind
yarn add astro@latest @astrojs/react@latest @astrojs/tailwind@latest

Instalar um número de versão específico

Para instalar uma determinada versão do Astro ou integrações, use o comando apropriado para seu gerenciador de pacotes.

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

Atualizações da documentação

Esta documentação é atualizada para cada lançamento de versão minor e de versão major. Quando novas funcionalidades forem adicionadas ou o uso existente mudar, a documentação será atualizada para refletir o comportamento atual do Astro. Se o seu projeto não for atualizado, você poderá notar que alguns comportamentos não correspondem à documentação atualizada.

Novas funcionalidades são adicionadas à documentação com o número da versão específica em que foram adicionadas. Isso significa que, se você não tiver atualizado para a versão mais recente do Astro, alguns recursos documentados poderão não estar disponíveis. Sempre verifique o número da versão Adicionado em: e certifique-se de que seu projeto esteja atualizado antes de tentar usar as novas funcionalidades!

Se você não tiver feito a atualização para a versão major mais recente do Astro, poderá encontrar diferenças significativas entre a documentação do Astro e o comportamento do seu projeto. Recomendamos enfaticamente a atualização para a versão major atual do Astro assim que for possível. Tanto o código quanto a documentação das versões anteriores não têm suporte.

Guias de atualização

Após cada nova versão major, você encontrará um guia de atualização com informações sobre alterações importantes e instruções para atualizar o código do seu projeto.

As principais páginas de documentação do Astro são sempre específicas para a última versão lançada do Astro. Elas não descrevem nem comparam como as coisas funcionavam em versões anteriores, nem destacam comportamentos atualizados ou alterados.

Consulte os guias de atualização abaixo para obter uma explicação das alterações, comparando a nova versão com a antiga. Os guias de atualização incluem tudo o que pode exigir que você altere seu próprio código: alterações significativas, descontinuações, remoções e substituições de funcionalidades, bem como orientações de uso atualizadas. Cada alteração no Astro inclui uma seção “O que devo fazer?” para ajudá-lo a atualizar o código do seu projeto de maneira bem-sucedida.

Documentação antiga (sem manutenção)

A documentação para versões mais antigas do Astro não é mantida, mas está disponível como um arquivo estático. Use essas versões da documentação se você não puder atualizar seu projeto, mas ainda quiser consultar guias e referências:

Versionamento Semântico

O Astro tenta aderir o máximo possível ao versionamento semântico, que é um conjunto de regras que os desenvolvedores usam para determinar como atribuir um número de versão a uma versão nova. A versão semântica segue um padrão previsível para informar aos usuários o tipo de alterações que eles podem esperar de uma versão para a outra.

O versionamento semântico impõe um padrão de X.Y.Z para números de versão de software. Esses valores representam atualizações major (X), minor (Y) e patch (Z).

Mudanças patch

As mudanças patch são as menos disruptivas. Elas não alteram a maneira como você usa o Astro, e nenhuma alteração em seu próprio código é necessária quando você faz a atualização.

Quando o Astro emite uma versão “patch”, o último número aumenta (por exemplo, astro@4.3.14 -> astro@4.3.15).

Correções podem ser lançadas por motivos como:

Alterações internas que não alteram a funcionalidade do Astro:
- refatorações
- melhorias de performance
- aumento ou alteração na cobertura de testes
- alinhamento com a documentação e o comportamento esperado
Melhorias no logging e nas mensagens de erro.
Relançamentos após uma falha de lançamento de nova versão.

As mudanças patch também incluem a maioria das correções de bugs, mesmo nos casos em que os usuários estavam tirando proveito de um comportamento existente não intencional ou indesejável.

Mudanças minor

As versões minor introduzem principalmente novos recursos e melhorias que você pode querer experimentar, mas não exigem alterações no seu código. Alguns recursos existentes também podem ser descontinuados (marcados para exclusão em uma versão futura, embora continuem funcionando) em uma versão minor, dando-lhe a oportunidade de se preparar para sua eventual remoção.

As versões minor incluem alterações como:

Descontinuação de funcionalidades/opções existentes com um aviso de que elas serão removidas em uma próxima versão major.
Introdução de novas funcionalidades.
Introdução de novas opções nos hooks de integração.
Introdução de novas funcionalidades em astro/app, usadas principalmente para criar novos adaptadores.

Uma versão minor também pode incluir alterações patch.

Mudanças major

As versões major incluirão mudanças significativas em pelo menos alguns códigos existentes. Essas alterações são sempre documentadas em um guia “Atualize para vX” no Astro.

As versões major permitem que o Astro faça alterações significativas não apenas na lógica interna, mas também no comportamento e no uso esperados. A documentação será atualizada para refletir apenas a versão mais recente, e arquivos estáticos e não mantidos de documentações mais antigas estão disponíveis como um registro histórico para projetos mais antigos que ainda não foram atualizados.

As versões major incluem alterações como:

Remoção de funcionalidades anteriormente descontinuadas.
Alterações das funcionalidades existentes.
Alterações das opções existentes nos hooks de integração.
Alterações das opções e funcionalidades existentes em astro/app, usadas principalmente para criar novos adaptadores.

Uma versão major também pode incluir algumas alterações e melhorias não disruptivas que normalmente seriam lançadas separadamente em uma versão minor ou patch.

Exceções

Funcionalidades experimentais. O lançamento de versões do Astro sem aderir ao versionamento semântico permite que os desenvolvedores do Astro tenham a maior flexibilidade para explorar, e até mesmo mudar radicalmente o curso, durante o desenvolvimento de funcionalidades experimentais. Portanto, o comportamento desses recursos pode ser alterado em alterações minor e patch.

Esses recursos geralmente são acompanhados por uma fase 3 de Solicitação de Consideração (RFC) pública e em andamento. Espera-se que os usuários beta acompanhem as atualizações e deixem um feedback preliminar na discussão para ajudar a orientar o desenvolvimento dessas funcionalidades.

Quando esses recursos saírem do período experimental, eles seguirão o contrato normal de versionamento semântico.
Melhorias na documentação (por exemplo, mensagens de referência e de erro). Elas são criadas a partir do código-fonte para o repositório docs. Isso permite que o Astro atualize rapidamente as correções e melhorias da documentação nos casos em que o conteúdo de origem da documentação é armazenado no repositório principal astro.

Políticas de suporte e atualização do Node.js

Suporte

O Astro é compatível com a versão de Manutenção LTS (suporte de longo prazo) mais recente do Node.js.
O Astro é compatível com a versão Ativa LTS (suporte de longo prazo) atual do Node.js.
O Astro pode oferecer suporte a versões ímpares do Node.js.

Atualização

As regras a seguir definem quando o Astro pode descontinuar, abandonar ou adicionar suporte para versões do Node.js:

As versões ímpares do Node.js podem ser depreciadas e/ou abandonadas quando a próxima versão par do Node.js for publicada. Essa alteração pode ocorrer em uma versão minor do Astro, após um período razoável de suporte estendido, conforme decidido pela equipe Core do Astro.
A atualização da versão mínima de Manutenção LTS (dentro da mesma versão major, por exemplo, de v18.14.* para v18.20.*) do Node.js pode ocorrer em uma versão minor do Astro.
- Exceção de segurança: Se uma falha de segurança no Node.js que afeta o Astro for divulgada e corrigida, a equipe Core poderá aumentar a versão mínima de Manutenção LTS em uma versão patch.
O upgrade de versões minor ou major do Node.js (não Manutenção LTS) ocorre apenas nas versões major do Astro.
- Exceção de segurança: Se uma falha de segurança no Node.js que afeta o Astro for divulgada e corrigida, a equipe Core poderá aumentar a versão mínima em uma versão minor do Astro.

Manutenção estendida

A equipe Core fornecerá manutenção estendida para correções de segurança apenas para uma versão major anterior. Isso significa que, se a versão major atual for a v4.*, a equipe Core fará a portabilidade das correções de segurança e emitirá uma nova versão v3.*.

Contribua

Comunidade