Breaking Change Policy

이 문서는 Haystack의 브레이킹 체인지(breaking change) 정책을 설명해요. 브레이킹 체인지의 정의, 버전 규약, 그리고 기존 기능의 폐기(deprecation) 과정을 다룹니다.

Haystack은 활발히 개발 중이라 기능이 자주 추가·폐기·제거돼요. 이 정책은 이러한 변경이 현재 사용자와 배포에 미치는 영향을 최소화하는 것을 목표로 해요. 명확한 일정을 제공하고, 새 Haystack 버전으로 업그레이드하기 전에 필요한 단계를 설명합니다.

출처: 문서

본문

Breaking Change Definition

다음 중 하나가 발생하면 브레이킹 체인지예요:

컴포넌트가 제거되거나 이름이 바뀌거나 Python import 경로가 변경된 경우
파라미터가 이름이 바뀌거나 제거되거나 선택에서 필수로 바뀐 경우
새 필수 파라미터가 추가된 경우

기존 배포가 깨질 수 있으며, 그 변경은 브레이킹 체인지로 간주됩니다. 변경을 브레이킹으로 선언할지 여부는 그 잠재적 영향과는 무관해요: 특정 Haystack 기능을 쓰는 아주 작은 애플리케이션 부분에만 영향을 줘도 여전히 브레이킹 체인지로 취급됩니다.

다음 경우는 브레이킹 체인지로 간주하지 않아요:

새 기능이 추가된 경우(예: 새 컴포넌트)
컴포넌트·클래스·유틸리티 함수에 새 선택 파라미터가 추가된 경우
기존 파라미터가 필수에서 선택으로 바뀐 경우

기존 배포는 영향을 받지 않으며, 그 변경은 논-브레이킹으로 간주됩니다. 릴리스 노트는 변경을 언급하고 업그레이드 경로를 제공할 수도 있지만, Haystack을 업그레이드해도 기존 애플리케이션은 깨지지 않아요.

Versioning

Haystack 릴리스는 점으로 구분된 세 숫자로 표시됩니다. 예를 들어 2.0.1이죠. 각 숫자는 특정 의미를 가져요:

2는 Major(주) 버전
0은 Minor(부) 버전
1은 Patch(패치) 버전

info 비슷하지만, Haystack은 시맨틱 버저닝(Semantic Versioning) 원칙을 따르지 않아요. 차이점을 계속 읽어 보세요.

MAJOR.MINOR.PATCH 형식의 버전 번호를 가진 Haystack 릴리스에서는 다음을 기대해야 합니다:

Major 버전 변경: 근본적이고 호환되지 않는 API 변경. 이 경우 Haystack을 업데이트하기 전에 마이그레이션 과정이 필요할 가능성이 높아요. Major 릴리스는 1년에 한 번 이상 발생하지 않으며, 변경 사항은 광범위하게 문서화되고 마이그레이션 경로가 제공됩니다.
Minor 버전 변경: 이전 버전과 호환되지 않을 수 있는 기능의 추가 또는 제거. 대부분의 경우 Haystack 설치를 매끄럽게 업그레이드할 수 있지만, 항상 릴리스 노트를 참고하세요. 폐기된 컴포넌트는 Minor 버전 릴리스에서 제공되는 가장 흔한 브레이킹 체인지입니다.
Patch 버전 변경: 버그 수정. 프로그램이 깨질 걱정 없이 안전하게 Haystack을 새 버전으로 업그레이드할 수 있어요.

Deprecation of Existing Features

Haystack은 견고함을 지향해요. 이를 위해 더 이상 사용되지 않는 오래된 기능을 제거하며 코드를 정리합니다. 이는 코드베이스 유지, 보안 개선, 그리고 모든 것이 원활하게 돌아가도록 유지하는 데 도움이 됩니다. 기능·컴포넌트·클래스·유틸리티 함수를 제거하기 전에 폐기(deprecation)라는 과정을 거칩니다.

Major 또는 Minor(단 Patch는 아님) 버전이 이전 릴리스의 특정 기능을 폐기할 수 있으며, 이때 다음을 기대해야 합니다:

기능이 Haystack 버전 X.Y에서 폐기되면 계속 동작하지만, Python 코드가 업그레이드하기 위해 따라야 할 단계를 상세히 알려주는 경고를 발생시켜요.
Haystack 버전 X.Y에서 폐기된 기능은 Haystack X.Y+1에서 제거되어, 영향을 받는 사용자에게 업그레이드를 준비할 대략 한 달의 시간을 줍니다.

Example

과정을 명확히 하기 위한 예시입니다:

어느 시점에 FooComponent를 제거하기로 하고 Haystack 버전 2.99.0에서 폐기로 선언한다고 해봅시다. 다음이 일어납니다:

FooComponent는 Haystack 2.99.0에서 평소처럼 계속 동작하지만, 컴포넌트를 사용하면 코드에 FutureWarning 메시지가 발생해요.
Haystack 버전 2.100.0에서 코드베이스에서 FooComponent를 제거합니다. 사용을 시도하면 오류가 발생해요.

Discontinuing an Integration

기존 기능이 변경되거나 제거될 때, 통합도 Haystack에 대해 이 페이지에 설명된 것과 같은 폐기 과정을 거칩니다. 통합은 독립적이며 자체 패키지로 배포된다는 점을 기억하는 게 중요해요. 어떤 경우에는 통합이 중단되고 이후 Core Integrations 저장소에서 제거되는 특별한 형태의 폐기가 발생할 수 있습니다.

커뮤니티에 통합을 인수하고 중단 전에 계속 유지할 기회를 주기 위해, Core Integrations는 아래에 설명된 다양한 상태를 점진적으로 거칩니다:

Staged(스테이징됨)
- 통합의 소스 코드가 Core Integrations 저장소의 main에서 특별한 staging 가지로 이동됩니다.
- 문서 페이지는 Haystack 문서 웹사이트에서 제거됩니다.
- Core Integrations 저장소의 메인 README에 커뮤니티가 통합을 채택하는 방법을 설명하는 고지가 표시됩니다.
- 통합 타일이 제거됩니다(인수한 메인테이너가 나중에 다시 추가할 수 있음).
- PyPI의 통합 패키지는 계속 사용 가능합니다.
- 3개월의 유예 기간이 시작됩니다.
Adopted(채택됨)
- 커뮤니티의 조직이나 개인이 Staged 통합의 소유권을 인수하는 것을 수락합니다.
- 채택자는 자체 저장소를 만들고, 중단된 통합의 소스 코드는 staging 가지에서 제거됩니다.
- PyPI 패키지의 소유권이 새 메인테이너에게 이전됩니다.
- 채택자는 haystack-integrations에 새 통합 타일을 만듭니다.
Discontinued(중단됨)
- 유예 기간이 만료되고 아무도 Staged 통합을 채택하지 않으면, 소스 코드가 staging 가지에서 제거됩니다.
- 통합의 PyPI 패키지는 제거되지 않지만 더 이상 업데이트되지 않습니다.

더 알아보기 (Learn more)

릴리스 노트 — 각 버전의 변경 사항
Haystack GitHub — 저장소