Astro 업그레이드

이 가이드에서는 Astro 버전 및 관련 종속성을 업데이트하는 방법, 한 버전에서 다음 버전으로 변경된 내용을 알아보는 방법, Astro의 버전 관리 시스템 및 해당 문서 업데이트를 이해하는 방법에 대해 설명합니다.

달라진 점은 무엇인가요?

현재 Astro의 최신 릴리스는 v4.16.16 입니다.

모든 변경사항의 전체 목록은 Astro의 변경 로그에서, 새로운 주버전 버전으로 업그레이드하는 데 필요한 중요한 지침은 업그레이드 가이드에서 확인할 수 있습니다.

문서 업데이트

이 문서는 부버전 릴리스 및 주버전 버전 릴리스가 있을 때마다 업데이트됩니다. 새로운 기능이 추가되거나, 기존 사용법이 변경되면, 문서가 업데이트되어 Astro의 현재 동작을 반영합니다. 프로젝트가 업데이트되지 않은 경우, 일부 동작이 최신 문서와 일치하지 않을 수 있습니다.

새로운 기능은 추가된 특정 버전 번호와 함께 문서에 추가됩니다. 즉, 최신 버전의 Astro로 업데이트하지 않은 경우 일부 문서화된 기능을 사용하지 못할 수 있습니다. 새로운 기능을 사용하기 전에 항상 Added in: 버전 번호를 확인하고 프로젝트가 업데이트되었는지 확인하세요!

최신 주버전 버전의 Astro로 업그레이드하지 않은 경우, Astro 문서와 프로젝트의 동작 간에 상당한 차이가 발생할 수 있습니다. 가능한 한 빨리 현재 주버전 버전의 Astro로 업그레이드할 것을 강력히 권장합니다. 이전 버전의 코드와 문서는 모두 지원되지 않습니다.

업그레이드 가이드

모든 주버전 버전 릴리스 이후에는 중요한 변경 사항에 대한 정보와 프로젝트 코드 업그레이드 지침이 포함된 업그레이드 가이드를 확인할 수 있습니다.

Astro의 기본 문서 페이지는 항상 최신 출시된 버전의 Astro에 대해 정확합니다. 이전 버전의 작동 방식을 설명하거나 비교하지 않으며, 업데이트되거나 변경된 동작을 강조하지도 않습니다.

아래 업그레이드 가이드에서 새 버전과 이전 버전을 비교하여 변경 사항에 대한 설명을 확인하세요. 업그레이드 가이드에는 변경 사항, 사용 중단, 기능 제거 및 대체, 업데이트된 사용 안내 등 코드를 변경해야 할 수 있는 모든 내용이 포함되어 있습니다. Astro의 각 변경 사항에는 프로젝트 코드를 성공적으로 업데이트하는 데 도움이 되는 “어떻게 해야 하나요?” 섹션이 포함되어 있습니다.

이전 문서 (관리되지 않음)

이전 버전의 Astro에 대한 문서는 유지 관리되지 않지만 정적 스냅샷으로 제공됩니다. 프로젝트를 업그레이드할 수 없지만 가이드와 참고 자료가 필요한 경우 이러한 버전의 문서를 사용하세요:

유의적 버전 관리

Astro는 개발자가 릴리스에 버전 번호를 할당하는 방법을 결정하는 데 사용하는 일련의 규칙인 유의적 버전 관리를 최대한 준수하려고 노력합니다. 유의적 버전은 예측 가능한 패턴을 따라 사용자에게 한 버전에서 다음 버전으로 예상할 수 있는 변경 사항을 알려줍니다.

유의적 버전 관리에서는 소프트웨어 버전 번호에 ‘X.Y.Z’의 패턴을 적용합니다. 이 값은 주(X), 부(Y), 수(Z) 업데이트를 나타냅니다.

수버전 변경

수버전 변경은 가장 방해가 적은 변경입니다. 수버전은 Astro 사용 방식을 변경하지 않으며 업데이트할 때 자체 코드를 변경할 필요가 없습니다.

아스트로가 “수” 버전을 발행하면 마지막 숫자가 증가합니다. (예: astro@4.3.14 -> astro@4.3.15)

수버전은 다음과 같은 이유로 릴리스될 수 있습니다:

Astro의 기능을 변경하지 않는 내부 변경 사항입니다:
- 리팩토링
- 성능 개선
- 테스트 커버리지의 증가 또는 변경
- 명시된 문서 및 예상 동작과 일치
로깅 및 오류 메시지 개선.
실패한 릴리스 후 다시 릴리스.

수버전 변경에는 사용자가 기존의 의도하지 않았거나, 바람직하지 않은 동작을 이용하던 경우에도 대부분의 버그 수정이 포함됩니다.

부버전 변경

부버전 릴리스는 주로 사용해 볼 수 있는 새로운 기능과 개선 사항을 소개하지만 코드를 변경할 필요는 없습니다. 부버전 릴리스에서는 일부 기존 기능이 사용 중단(계속 작동하지만 향후 버전에서 삭제될 것으로 표시됨)될 수도 있으므로 최종 제거에 대비할 수 있는 기회를 제공합니다.

부버전 릴리스에는 다음과 같은 변경 사항이 포함되어 있습니다:

향후 주버전 릴리스에서 제거될 것이라는 경고와 함께 기존 기능/옵션의 사용 중단이 표시됩니다.
새로운 기능 도입.
통합 후크에 새로운 옵션 도입.
새로운 어댑터를 만드는 데 주로 사용되는 astro/app에 새로운 기능 도입.

부버전 릴리스에는 소규모 수버전 변경 사항도 동시에 포함될 수 있습니다.

주버전 변경

주버전 릴리스에는 최소한 일부 기존 코드에 대한 획기적인 변경 사항이 포함됩니다. 이러한 중요한 변경 사항은 항상 Astro의 “vX로 업그레이드” 가이드에 문서화되어 있습니다.

주버전 릴리스에서는 내부 로직뿐만 아니라 의도된 동작과 사용법도 크게 변경할 수 있습니다. 문서는 최신 버전만 반영하도록 업데이트되며, 아직 업그레이드되지 않은 이전 프로젝트의 기록으로 이전 문서의 유지 관리되지 않은 정적 스냅샷을 사용할 수 있습니다.

주버전 릴리스에는 다음과 같은 변경 사항이 포함되어 있습니다:

이전에 더 이상 사용되지 않는 기능의 제거.
기존 기능의 변경.
통합 후크의 기존 옵션 변경.
새 어댑터를 만드는 데 사용되는 astro/app의 기존 옵션 및 기능 변경.

주버전 릴리스에는 일반적으로 부버전 릴리스나 수버전 릴리스에서 별도로 릴리스되는 일부 중요하지 않은 변경 사항과 개선 사항도 포함될 수 있습니다.

예외 사항

실험적 기능. 유의적 버전 관리를 준수하지 않고 Astro 버전을 출시하면, Astro 개발자가 실험적 기능을 개발하는 동안 최대한 유연하게 탐색하고, 심지어 방향을 급격하게 변경할 수 있습니다. 따라서 이러한 기능의 동작은 부버전 및 수버전 변경으로 인해 중단될 수 있습니다.

이러한 기능은 일반적으로 진행 중인 공개 검토 요청(RFC) 3단계와 함께 제공됩니다. 우리는 베타 사용자들에게 이러한 기능의 개발 방향에 도움이 될 수 있도록 업데이트를 확인하고, 토론에 대한 피드백을 조기에 남길 것으로 기대합니다.

이러한 기능은 실험 기간이 끝나면 일반적인 유의적 버전 관리 계약을 따르게 됩니다.
문서 개선 사항(예: 참조 및 오류 메시지). 이는 docs 리포지토리의 소스로부터 빌드됩니다. 이를 통해 문서 소스 콘텐츠가 기본 astro 리포지토리에 저장되어 있는 경우 Astro에서 문서 수정 및 개선 사항을 신속하게 업데이트할 수 있습니다.

Node.js 지원 및 업그레이드 정책

지원

Astro는 최신 Maintenance LTS 버전의 Node.js를 지원합니다.
Astro는 현재 Active LTS 버전의 Node.js를 지원합니다.
Astro는 Node.js의 홀수 버전을 지원할 수 있습니다.

업그레이드

다음 규칙은 Astro가 Node.js 버전에 대한 지원을 중단, 삭제 또는 추가할 수 있는 시기를 정의합니다.

Node.js의 홀수 버전은 Node.js의 다음 짝수 버전이 게시될 때 더 이상 사용되지 않거나 삭제될 수 있습니다. 이 변경 사항은 Astro Core 팀이 결정한 대로 합당한 확장 지원 기간이 끝난 후 Astro의 부 릴리스에서 발생할 수 있습니다.
Node.js의 최소 Maintenance LTS (동일한 주버전 범위와 함께, 예를 들어 v18.14.*에서 v18.20.*로) 버전 업그레이드는 Astro의 부 릴리스에서 발생할 수 있습니다.
- 보안 예외: Astro에 영향을 미치는 Node.js의 보안 결함이 공개되어 수정되면 Core 팀은 수 릴리스에서 Maintenance LTS의 최소 버전을 높일 수 있습니다.
Node.js의 부 또는 주버전 업그레이드 (Maintenance LTS 아님)는 Astro의 주버전에서만 발생합니다.
- 보안 예외: Astro에 영향을 미치는 Node.js의 보안 결함이 공개되어 수정되면 Core 팀은 부 릴리스에서 최소 버전을 높일 수 있습니다.

연장된 유지 관리

Core 팀은 이전 주버전에 대해 보안 수정을 위해서만 연장된 유지 관리를 제공할 것입니다. 즉, 현재 주버전이 v4.*인 경우 코어 팀은 포트 보안 수정 사항을 지원하고 새로운 v3.* 릴리스를 발행할 것입니다.

기여하기

커뮤니티