릴리스 및 버저닝 정책

원문 보기 위키 갱신 2026.10.07

Backstage 프로젝트는 함께 Backstage 플랫폼을 형성하는 소프트웨어 구성 요소 집합으로 구성돼요. 이 구성 요소는 플러그인뿐 아니라 핵심 플랫폼 라이브러리와 도구도 포함해요. 각 구성 요소는 패키지 모음으로 배포되며, 결국 Backstage 도입자로서 소비하는 것이 바로 그것이에요.

출처: 문서

본문

애플리케이션을 구성하는 Backstage 패키지 수는 수백 개에 이를 만큼 상당히 클 수 있으며, 핵심 플랫폼 패키지만도 십수 개에 달해요. 이는 Backstage 프로젝트의 통합자에게 도전 과제를 만들는데, 최신 상태로 유지해야 할 많은 움직이는 부품이 있기 때문이에요.

이에 대한 우리의 해결책은 가장 많이 사용되는 구성 요소와 그 패키지들을 Backstage 릴리스(release)라는 어퍼엘라(umbrella) 버전으로 모으는 것이에요. 각 릴리스는 함께 작동하도록 검증된 특정 버전의 패키지 모음이에요. 배터리가 포함된 도구 상자라고 생각하면 되지만, 오픈소스 생태계에서 더 많은 플러그인과 라이브러리를 추가하고 직접 만들 수도 있어요.

릴리스 라인

Backstage 프로젝트는 두 가지 다른 릴리스 라인으로 구조화돼요. 주 "main" 릴리스 라인과, 다음 main 릴리스의 프리뷰·사전 릴리스 역할을 하는 "next" 릴리스 라인이에요. 각 릴리스 라인은 자체 릴리스 주기와 버저닝 정책을 가져요.

Main 릴리스 라인

릴리스 주기: 월간, 구체적으로 매월 셋째 수요일 전 화요일이에요. 첫 릴리스는 2022년 3월에 이루어졌어요.

main 릴리스 라인은 major, minor, patch 버전으로 버저닝되지만 semver를 따르지는 않아요. 버전 형식은 <major>.<minor>.<patch>이며, 예를 들어 1.3.0이에요.

major 버전의 증가는 Backstage 플랫폼에 대한 상당한 개선이나 변경을 의미해요. 대규모 새 기능 집합이 오거나 제품 방향의 전환이 있을 수 있어요. 이런 것들은 드물게 발생하며 정해진 주기가 없어요. 정책상으로는 minor 릴리스와 다르지 않아요.

각 정기 릴리스는 major 릴리스가 아닌 한 minor 버전의 증가를 가져와요. 각 새 minor 버전은 버저닝 정책에 따라 새 기능, 중단 변경, 버그 수정을 포함할 수 있어요.

patch 버전은 중요한 버그 수정을 해결하기 위해서만 릴리스돼요. 그것들은 정기 주기에 묶이지 않고 필요할 때마다 릴리스돼요.

Next 릴리스 라인

릴리스 주기: 주간, 구체적으로 화요일에요.

next 릴리스 라인은 프로젝트의 주간 릴리스예요. 이 릴리스를 사용하면 Backstage의 예정된 기능에 조기 접근할 수 있어요. 그러나 이 릴리스에서는 중단 변경에 대한 보장이 더 적으며, 한 릴리스에서 다음 릴리스로 이동할 때 상당한 중단 변경이 도입될 수 있어요.

릴리스 버저닝 정책

다음 버저닝 정책은 main 라인 릴리스에만 적용돼요.

>=1.0.0 버전에 도달한 패키지의 중단 변경은 필요할 때만, 최소한의 영향 목표로 이루어져요. 가능할 때 항상 중단 변경에 대한 deprecation 경로가 있어요.
보안 수정은 업그레이드 경로의 단순성과 취약점의 심각도에 따라 이전 릴리스로 백포트될 수 있어요. high 또는 critical 심각도의 취약점은 가능하면 지난 6개월 릴리스에 항상 백포트돼요.
버그 보고는 가장 최근 릴리스에서 재현 가능할 때만 유효하며, 버그 수정은 다음 릴리스에만 적용돼요.
우리는 이 정책을 지키기 위해 최선을 다할 거예요.

Skew 정책

Backstage가 제대로 기능하기 위해 다음 버저닝 규칙을 따라야 해요. 규칙은 Package Architecture를 가리켜요.

각 "App Core" 그룹의 모든 패키지 버전은 같은 Backstage 릴리스에서 나와야 해요.
각 프론트엔드·백엔드 설정에서 "App Core" 패키지는 설치된 모든 플러그인과 모듈의 전이 의존성을 포함해 "Plugin Core" 패키지보다 앞서거나 같은 Backstage 릴리스에 있어야 해요.
어떤 플러그인이든 "Plugin Core" 및 "Library" 그룹의 모든 패키지 버전은 같은 Backstage 릴리스에서 나와야 해요.
대응하는 백엔드 플러그인이 있는 프론트엔드 플러그인은 같은 릴리스에서 나와야 해요. 백엔드 플러그인으로의 업데이트는 프론트엔드 플러그인으로의 업데이트보다 먼저 또는 함께 배포되어야 해요(MUST).

"Plugin Core"와 "Library" 패키지가 "App Core" 패키지보다 오래된 릴리스에서 나오는 것은 허용되며 종종 기대돼요. "Plugin Core"와 "Library" 패키지의 중복 설치를 갖는 것도 허용돼요. 이 모든 것은 Backstage 업그레이드를 가능한 매끄럽게 만들고 전체 플러그인 생태계에 걸쳐 더 많은 유연성을 허용하기 위해서예요.

패키지 버저닝 정책

각 개별 패키지는 semver에 따라 버저닝돼요. 이 버저닝은 Backstage 릴리스 버저닝과 완전히 분리되어 있으며, 예를 들어 @backstage/core-plugin-api 버전 3.1.4가 1.12 Backstage 릴리스의 일부일 수 있어요.

다음 버저닝 정책은 모든 패키지에 적용돼요.

중단 변경은 changelog에 기록되고 문서가 갱신돼요.
중단 변경은 changelog에서 **BREAKING**: 접두사로 표시돼요.
모든 공개 export는 안정적인 것으로 간주되며 changelog에 항목이 있어요.
중단 변경은 changelog에 명확한 업그레이드 경로를 문서화하는 것을 권장해요. 새로 도입되었거나 불안정한 패키지에서는 이를 생략할 수 있어요.

1.0.0 이상 버전의 패키지에는 다음 정책도 적용돼요.

모든 export는 릴리스 단계로 표시돼요.
안정적인 export에 대한 중단 변경은 가능하면 deprecation 단계를 포함해요. deprecation은 제거되기 전에 최소한 한 번의 mainline 릴리스에 걸쳐 릴리스되어야 해요.
중단 변경 릴리스는 deprecation이 도입될 때와 제거될 때 모두 changelog에 명확한 업그레이드 경로를 문서화해요.
@alpha 또는 @beta export에 대한 중단 변경은 최소한 minor 버전 증가를 가져와야 하며, deprecation 기간 없이 이루어질 수 있어요.

중단으로 간주되지 않는 변경

일반적으로 중단 변경으로 간주되지만 예외를 두는 몇 가지 변경이 있어요. 이는 프로젝트를 더 빠르게 진화시킬 수 있게 하기 위해서이기도 하고, 대안이 사용자에게 더 큰 영향을 미치기 때문이기도 해요.

내장 구현이 있는 모든 Utility API와 Backend Service에 대해 우리는 해당 인터페이스의 소비자에 대한 API 안정성만 고려해요. 이는 인터페이스의 생산자에 대한 계약을 깨는 것이 중단 변경으로 간주되지 않음을 의미해요.

위 규칙에 해당하는 변경은 changelog에서 **BREAKING PRODUCERS**:로 표시되어야 해요.

의존성 주입의 어떤 경우든 프레임워크가 제공하는 Utility API나 Backend Service에 의존성을 추가하는 것은 중단 변경으로 간주되지 않아요. 이는 @backstage/app-defaults와 @backstage/backend-defaults 패키지가 제공하는 모든 의존성을 포함해요.

릴리스 단계

릴리스 단계(@alpha, @beta @public)는 export의 TSDoc 문서 태그를 말하며, 각 패키지의 API 리포트에서도 볼 수 있어요.

Backstage는 세 가지 단계를 사용해 각 개별 패키지 export의 안정성을 나타내요.

@public - 안정적인 것으로 간주되며 메인 패키지 진입점에서 사용할 수 있어요.
@beta - 메인 패키지 진입점에서 보이지 않으며, beta export는 <package-name>/beta 또는 <package-name>/alpha import로 접근해야 해요.
@alpha - 여기 용이 있어요(here be dragons). 메인 패키지 진입점에서 보이지 않으며, alpha export는 <package-name>/alpha import로 접근해야 해요.

Node.js 릴리스

Backstage 프로젝트는 개발 도구링과 백엔드 런타임 모두에 Node.js를 사용해요. 기대치를 명확히 하기 위해 우리가 지원하는 Node.js 릴리스를 결정하는 데 다음 일정을 사용해요.

어떤 시점이든 정확히 두 개의 인접한 짝수 번호 Node.js 릴리스를 지원해요. 예를 들어 v12와 v14.
새 Node.js 릴리스가 Active LTS가 되면 그 릴리스와 이전 릴리스를 지원하도록 전환해요. 전환은 즉시가 아니라 가능한 빨리 이루어져요. 각 릴리스가 지원하는 Node.js 버전은 새 앱의 루트 package.json의 engines 필드에서 찾을 수 있어요.

Node.js 릴리스를 지원한다고 할 때 다음을 의미해요.

기본 Backstage 저장소의 CI 파이프라인은 지원되는 릴리스에 대해 테스트하며, 다른 Backstage 관련 프로젝트도 그렇게 하도록 권장해요.
@backstage/create-app으로 만든 새 Backstage 프로젝트는 engines.node 버전이 그에 맞게 설정돼요.
지원되지 않는 릴리스와의 호환성 중단은 중단 변경으로 간주되지 않아요. 여기에는 새 구문이나 API 사용, 이 버전을 지원하지 않는 의존성 상향이 포함돼요.

위에 따라 Backstage는 1.46.0 릴리스 기준으로 Node.js 22와 24를 지원해요.

TypeScript 릴리스

Backstage 프로젝트는 프로젝트 내 타입 검사와 외부 API 및 문서에 TypeScript를 사용해요. 우리가 지원하는 TypeScript 버전에 대한 명확한 정책을 갖는 것이 중요해요. 새 TypeScript 기능을 채택하고 싶으면서도 동시에 이전 버전을 사용하는 기존 프로젝트를 깨뜨리지 않기를 원하기 때문이에요.

TypeScript 릴리스 주기는 대략 3개월마다예요. TypeScript 버저닝의 중요한 측면은 semver를 따르지 않는다는 점이에요. 특히 major와 minor 버전 사이에 구분이 없으며, 둘 다 중단 변경이에요. 한 가지 생각할 방법은 둘을 합치는 것이에요. 예를 들어 버전 4.7은 major 버전 47로, 5.0은 50으로 생각할 수 있어요. 이 릴리스 안에는 몇 가지 patch 릴리스가 있을 수 있으며, 그것들은 semver를 따라요.

우리의 정책은 최근 3개의 TypeScript 버전을 지원하는 것이에요. 예를 들어 4.8, 4.9, 5.0이에요. 시간으로 환산하면 TypeScript 릴리스 창의 어디에 있는지에 따라 보통 지난 6~9개월의 TypeScript 버전을 지원한다는 뜻이에요. 이 정책은 주어진 Backstage 릴리스 시점의 스냅샷으로 적용되며, 새 TypeScript 릴리스는 현재 릴리스가 아니라 다음 Backstage main 라인 릴리스에만 적용돼요.

자체 Backstage 프로젝트를 유지하는 사람에게 이는 적어도 6개월마다 최신 TypeScript 버전으로 올리도록 노력해야 하며, 그렇지 않으면 Backstage 패키지를 업그레이드할 때 중단을 겪을 수 있음을 의미해요. 그렇게 하는 데 문제가 있다면 기본 Backstage 저장소에 이슈를 제기하세요. 이 정책에 따라 우리는 항상 최신 버전을 지원해야 하기 때문이에요. 새 TypeScript 기능을 너무 일찍 사용하기 시작하지 않도록, Backstage 프로젝트 자체는 현재 지원 창의 시작 부분 버전을 사용해요. 위 예시에서는 버전 4.8이 되겠죠.

PostgreSQL 릴리스

Backstage 프로젝트는 영구 저장에 PostgreSQL 사용을 권장하고 지원해요.

PostgreSQL 버저닝 정책은 매년 새 기능으로 새 major 버전을 릴리스하며, 이것은 초기 릴리스 후 5년 동안 지원돼요.

우리의 정책은 PostgreSQL 버저닝 정책을 반영해요 — 마지막 5개 major 버전을 지원할 거예요. 또한 그 범위에서 가장 새 버전과 가장 오래된 버전을 테스트할 거예요. 예를 들어 현재 지원 범위가 14~18이라면 14와 18만 명시적으로 테스트할 거예요.