Pular para o conteúdo

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?

Seção intitulada O que mudou?

A versão mais recente do Astro é a v4.9.3.

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

Seção intitulada 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:

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

Atualização manual

Seção intitulada 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.

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

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

Seção intitulada 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.

Terminal window
npm install astro@4.5.3 @astrojs/react@3.0.10

Atualizações da documentação

Seção intitulada 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

Seção intitulada 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)

Seção intitulada 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

Seção intitulada 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

Seção intitulada 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

Seção intitulada 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

Seção intitulada 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

Seção intitulada 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

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

Suporte

Seção intitulada Suporte

Atualização

Seção intitulada 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

Seção intitulada 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.*.