Обновление Astro

В этом руководстве рассказывается о том, как обновить свою версию Astro и связанные с ней зависимости, как узнать, что изменилось от одной версии к другой, а также как понять систему версий Astro и соответствующие обновления документации.

Что изменилось?

Последняя версия Astro — v4.16.16.

Исчерпывающий список всех изменений вы найдете в списке изменений Astro, а важные инструкции по обновлению до каждой новой основной версии — в наших руководствах по обновлению.

Обновление до последней версии

Обновите версию Astro и всех официальных интеграций вашего проекта до последних версий одной командой с помощью менеджера пакетов:

# Обновление Astro и официальных интеграций вместе
npx @astrojs/upgrade

# Обновление Astro и официальных интеграций вместе
pnpm dlx @astrojs/upgrade

# Обновление Astro и официальных интеграций вместе
yarn dlx @astrojs/upgrade

Обновление вручную

Чтобы обновить Astro и интеграции до их текущих версий вручную, используйте соответствующую команду для вашего пакетного менеджера.

# Пример: обновление Astro с помощью интеграций React и Tailwind
npm install astro@latest @astrojs/react@latest @astrojs/tailwind@latest

# Пример: обновление Astro с помощью интеграций React и Tailwind
pnpm add astro@latest @astrojs/react@latest @astrojs/tailwind@latest

# Пример: обновление Astro с помощью интеграций React и Tailwind
yarn add astro@latest @astrojs/react@latest @astrojs/tailwind@latest

Установка определённой версии

Чтобы установить определённую версию Astro или интеграцию, используйте соответствующую команду для вашего менеджера пакетов.

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

Обновление документации

Эта документация обновляется для каждого минорного релиза и мажорного релиза. Когда будут добавлены новые функции или изменено существующее использование, документация будет обновляться, чтобы отразить текущее поведение Astro. Если ваш проект не обновляется, то вы можете заметить, что некоторые поведения не соответствуют актуальной документации.

Новые возможности добавляются в документацию с указанием номера версии, в которой они были добавлены. Это означает, что если вы не обновились до последней версии Astro, некоторые задокументированные функции могут быть недоступны. Всегда проверяйте номер версии в строке Добавлено в: и убедитесь, что ваш проект обновлен, прежде чем пытаться использовать новые функции!

Если вы не обновили Astro до последней основной версии, вы можете столкнуться с существенными различиями между документацией Astro и поведением вашего проекта. Мы настоятельно рекомендуем обновить Astro до текущей основной версии, как только у вас появится такая возможность. Как код, так и документация по более ранним версиям не поддерживаются.

Руководства по обновлению

После каждого релиза мажорной версии вы найдете руководство по обновлению, содержащее информацию о важных изменениях и инструкции по обновлению кода вашего проекта.

Основные страницы документации Astro всегда соответствуют последней выпущенной версии Astro. Они не описывают и не сравнивают то, как всё работало в предыдущих версиях, и не выделяют обновлённые или изменённые действия.

Объяснение изменений и сравнение новой версии со старой смотрите в руководствах по обновлению ниже. Руководства по обновлению включают в себя всё, что может потребовать от вас изменения собственного кода: критические изменения, устаревание, удаление и замена функций, а также обновлённое руководство по использованию. Каждое изменение в Astro включает в себя раздел «Что делать?». Раздел поможет вам успешно обновить код проекта.

Устаревшая документация (не поддерживается)

Документация по старым версиям Astro не поддерживается, но доступна в виде статического снимка. Используйте эти версии документации, если вы не можете обновить свой проект, но всё равно хотите обратиться к руководствам и справочникам:

Семантическое версионирование

Astro старается максимально придерживаться семантического версионирования, которое представляет собой набор правил, используемых разработчиками для определения того, как присваивать номер версии релизу. Семантическая версия следует предсказуемой схеме, чтобы информировать пользователей о том, какие изменения они могут ожидать от одной версии к другой.

Семантическое версионирование принудительно использует шаблон X.Y.Z для номеров версий программного обеспечения. Эти значения представляют собой мажорные (крупные) (X), минорные (незначительные) (Y) и патчевые (Z) обновления.

Патчевые изменения

Изменения патч-версий — это наименее разрушительные изменения. Они не меняют того, как вы используете Astro, и при обновлении не требуется вносить изменения в ваш собственный код.

Когда Astro выпускает патч-версию, последнее число увеличивается (например: astro@4.3.14 -> astro@4.3.15).

Патчи могут выпускаться по таким причинам, как:

Внутренние изменения, которые не меняют функциональность Astro:
- рефакторинг
- улучшение производительности
- увеличение или изменение тестового покрытия
- соответствие заявленной документации и ожидаемому поведению
Улучшены протоколирование и сообщения об ошибках.
Переиздание после неудачного релиза.

Патчевые релизы также включают большинство исправлений, даже в тех случаях, когда пользователи пользовались существующим непредусмотренным или нежелательным поведением.

Минорные изменения

Минорные релизы в основном представляют новые возможности и улучшения, которые вы можете попробовать, но не требуют изменений в вашем коде. Некоторые существующие функции также могут быть утрачены (помечены для удаления в будущей версии, но при этом сохранят свою функциональность) в минорных релизах, что даст вам возможность подготовиться к их последующему удалению.

Минорные версии включают такие изменения, как:

Устаревание существующих функций/опций с предупреждением о том, что они будут удалены в ближайшем крупном релизе.
Внедрение новых функциональных возможностей.
Введение новых опций в интеграционных хуках.
Внедрение новых функциональных возможностей в astro/app, в частности, используемых для создания новых адаптеров.

Минорный релиз может одновременно включать и более мелкие изменения патч-версий.

Мажорные изменения

Мажорные релизы будут включать в себя критические изменения по крайней мере некоторого существующего кода. Эти изменения всегда документируются в руководстве «Обновление до vX» в Astro.

Мажорные релизы позволяют Astro вносить значительные изменения не только во внутреннюю логику, но и в предполагаемое поведение и использование. Документация будет обновляться только для отражения последней версии, а статические, не поддерживаемые снимки старых документов доступны в качестве исторической записи для старых проектов, которые ещё не обновлены.

Мажорные релизы включают такие изменения, как:

Удаление ранее объявленных устаревшими функций.
Изменения существующих функциональных возможностей.
Изменение существующих опций в интеграционных хуках.
Изменения существующих опций и функциональных возможностей в astro/app, в частности, используемых для создания новых адаптеров.

Мажорный релиз может также включать в себя некоторые не ломающие изменения и улучшения, которые обычно выпускаются отдельно в минорном или патчевом релизе.

Исключения

Экспериментальные возможности. Выпуск версий Astro без соблюдения семантического версионирования позволяет разработчикам Astro максимально гибко исследовать и даже радикально менять курс при разработке экспериментальных функций. Поэтому поведение этих функций может нарушаться при незначительных изменениях и патчах.

Эти возможности обычно сопровождаются текущим публичным запросом на рассмотрение (RFC) 3 стадии. Ожидается, что пользователи бета-версии будут следить за обновлениями и оставлять ранние отзывы в обсуждениях, чтобы помочь направить развитие этих функций.

Как только эти функции выйдут из экспериментального периода, они будут следовать обычному контракту семантического версионирования.
Улучшения в документации (например, ссылки и сообщения об ошибках). Они собираются из исходных текстов для репозитория docs. Это позволяет Astro быстро обновлять исправления и улучшения документации в тех случаях, когда исходный контент документации хранится в основном репозитории astro.

Политика поддержки и обновления Node.js

Поддержка

Astro поддерживает последнюю обслуживаемую LTS версию Node.js.
Astro поддерживает текущую активную LTS версию Node.js
Astro может поддерживать нечётные версии Node.js.

Обновление

Следующие правила определяют, в каких случаях Astro может прекратить, отменить или добавить поддержку версий Node.js:

Нечётные версии Node.js могут быть устаревшими и/или отменёнными, когда будет опубликована следующая чётная версия Node.js. Это изменение может произойти в минорном релизе Astro, после разумного периода расширенной поддержки по решению команды Astro Core.
Обновление минимальной Maintenance LTS (в том же мажорном диапазоне, например, от v18.14.* до v18.20.*) версии Node.js может произойти в минорном релизе Astro.
- Исключение из правил безопасности: Если недостаток безопасности в Node.js, который затрагивает Astro, будет раскрыт и исправлен, команда Core может повысить минимальную версию Maintenance LTS в патчевом релизе.
Обновление минорных или мажорных версий Node.js (не Maintenance LTS) происходит только в мажорных версиях Astro.
- Исключение из правил безопасности: Если недостаток безопасности в Node.js, который затрагивает Astro, будет раскрыт и исправлен, команда Core может повысить минимальную версию в минорном релизе.

Расширенное техническое обслуживание

Команда Core будет предоставлять расширенное обслуживание только для исправлений безопасности для одной предыдущей основной версии. Это означает, что если текущий мажор — v4.*, команда Core вернется к исправлениям безопасности и выпустит новый релиз v3.*.

Внести свой вклад

Сообщество