Astroのアップグレード

このガイドでは、Astroや関連する依存関係のバージョンを更新する方法、バージョン間で何が変更されたかを調べる方法、そしてAstroのバージョニングシステムとそれに対応するドキュメントの更新を理解する方法について説明します。

変更点は何ですか？

Astroの最新リリースはv4.7.1です。

すべての変更の詳細なリストはAstroの変更履歴で確認できます。また、各メジャーバージョンへのアップグレードに関する重要な説明は、アップグレードガイドに記載されています。

ドキュメントの更新

このドキュメントは、マイナーリリースおよびメジャーバージョンリリースごとに更新されます。新機能が追加されたり、既存の使用方法が変更されたりすると、ドキュメントは現在のAstroの挙動を反映するように更新されます。自分のプロジェクトを更新していない場合、最新のドキュメントと一部の挙動が一致しないことに気づくかもしれません。

新機能は、それらが追加された特定のバージョン番号と共にドキュメントに追加されます。これは、Astroの最新リリースに更新していない場合、ドキュメント化された一部の機能が利用できないことを意味します。新機能を使用する前に、常にAdded in:のバージョン番号を確認し、プロジェクトが更新されていることを確認してください！

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における新機能の導入。

マイナーリリースには、同時に小さなパッチレベルの変更も含まれる場合があります。

メジャーレベルの変更

メジャーリリースには、少なくとも一部の既存コードに影響を与える破壊的変更が含まれます。これらの破壊的変更は常にAstroの「vXへのアップグレード」ガイドに文書化されています。

メジャーリリースにより、Astroは内部ロジックだけでなく、意図された挙動や使用法にも大きな変更を加えられます。ドキュメントは最新バージョンのみを反映するよう更新され、静的でメンテナンスされていない古いドキュメントのスナップショットは、まだアップグレードされていない古いプロジェクトのための歴史的記録として残されます。

メジャーリリースには、以下のような変更が含まれます。

以前に非推奨とされた機能の削除。
既存機能の変更。
インテグレーションフック内の既存オプションの変更。
特に新しいアダプターの作成に使用されるような、astro/app内の既存オプションおよび機能の変更。

メジャーリリースには、通常、マイナーリリースやパッチリリースで個別にリリースされる非破壊的変更や改善も含まれる場合があります。

例外

実験的機能。実験的機能の開発中、セマンティックバージョニングに従わずにAstroのバージョンをリリースできれば、Astroの開発者は柔軟に事に当たることができ、根本的な方向転換さえも可能になります。そのため、これらの機能の挙動はマイナーレベルやパッチレベルの変更で壊れる可能性があります。

これらの機能は通常、進行中のパブリックなRFCステージ3が付属しています。ベータユーザーがアップデートをフォローし、議論に早期のフィードバックを残して、これらの機能の開発を支援することが期待されています。

これらの機能が実験期間を終えると、通常のセマンティックバージョニングの規約に従います。
ドキュメントの改善（例：リファレンスとエラーメッセージ）。これらはdocsリポジトリのためにソースコードからビルドされます。これにより、ドキュメントのもととなるコンテンツがメインのastroリポジトリに格納されている場合、Astroはドキュメントの修正と改善を迅速に更新できます。

Node.jsのサポートとアップグレードポリシー

サポート

AstroはNode.jsの最新の Maintenance LTSバージョンをサポートしています。
AstroはNode.jsの現在の Active LTSバージョンをサポートしています。
AstroはNode.jsの奇数バージョンをサポートしています。

アップグレード

次のルールは、AstroがNode.jsのバージョンのサポートを終了、削除、または追加するタイミングを定義します。

Node.jsの奇数バージョンは、次の偶数バージョンのNode.jsが公開されたときに非推奨化または削除されることがあります。この変更は、Astroコアチームによって決定された合理的なサポート期間の後、Astroのマイナーリリースで発生することがあります。
Node.jsの最小 Maintenance LTSバージョンのアップグレード（v18.14.*からv18.20.*へなど、同じメジャーレンジ内）は、Astroのマイナーリリースで行われることがあります。
- セキュリティのための例外：Node.jsのセキュリティ上の欠陥が公開・修正され、それがAstroに影響を与える場合、コアチームはパッチリリースで最小バージョンの Maintenance LTSを上げることができます。
Node.jsのマイナーレベルやメジャーレベルのアップグレード（非Maintenance LTS）は、Astroのメジャーバージョンでのみ行われます。
- セキュリティのための例外：Node.jsのセキュリティ上の欠陥が公開・修正され、それがAstroに影響を与える場合、コアチームはマイナーリリースで最小バージョンを上げることができます。