Astro 업그레이드

이 가이드에서는 Astro 버전 및 관련 의존성을 업데이트하는 방법, 버전별 변경 사항을 확인하는 방법, Astro의 버전 관리 시스템과 해당 문서 업데이트를 이해하는 방법을 다룹니다.

무엇이 바뀌었나요?

Astro의 최신 릴리스 버전은 v5.4.0입니다.

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 Core 팀이 결정한 합리적인 연장 지원 기간 후 Astro의 마이너 릴리스에서 발생할 수 있습니다.
Node.js의 최소 Maintenance LTS (동일한 주버전 범위와 함께, 예를 들어 v18.14.*에서 v18.20.*로) 버전 업그레이드는 Astro의 부 릴리스에서 발생할 수 있습니다.
최소 Maintenance LTS 버전 (동일한 메이저 범위 내, 예를 들어 v18.14.*에서 v18.20.*)의 Node.js 업그레이드는 Astro의 마이너 릴리스에서 발생할 수 있습니다.
- 보안 예외: Astro에 영향을 미치는 Node.js의 보안 결함이 발견되어 수정된 경우, Core 팀은 패치 릴리스에서 최소 Maintenance LTS 버전을 높일 수 있습니다.
마이너 또는 메이저 버전의 Node.js 업그레이드 (Maintenance LTS 제외)는 Astro의 메이저 버전에서만 발생합니다.
- 보안 예외: Astro에 영향을 미치는 Node.js의 보안 결함이 발견되어 수정된 경우, Core 팀은 마이너 릴리스에서 최소 버전을 높일 수 있습니다.

연장된 유지 관리

Core 팀은 이전 메이저 버전에 대해 보안 수정 사항에 한하여 연장된 유지 관리를 제공합니다. 즉, 현재 메이저 버전이 v4.*인 경우 Core 팀은 보안 수정 사항을 백포트하고 새로운 v3.* 릴리스를 발행합니다.

기여하기 커뮤니티 후원하기