버전 체계 정리

versioning.md

버전 포맷 (SemVer 2.0.0 기준)

<주번호>.<부번호>.<패치번호>[-<사전 릴리스>][+<빌드 메타데이터>]

일반 버전

• 주 번호 (MAJOR)
  • 하위 호환되지 않는 변경(breaking change)
  • 이하 버전 초기화 (e.g. v1.3.5 -> v2.0.0)
• 부 번호 (MINOR)
  • 하위 호환되는 신규 기능 추가
  • 기존 기능을 deprecated로 표시하는 경우 반드시 부 번호를 올립니다 (SemVer 2 스펙 7항)
  • 패치 번호 초기화 (e.g. v1.3.5 -> v1.4.0)
• 패치 번호 (PATCH)
  • 하위 호환되는 버그 수정
  • 내부 구현 개선 등 공개 API에 영향 없는 변경 포함 가능

초기 개발 단계 (0.y.z)

• 0.y.z는 초기 개발 단계로, 공개 API가 안정되지 않은 것으로 간주합니다. 어떤 것이든 언제든 변경될 수 있습니다.
• 1.0.0부터 공개 API가 확정되며, 이후 버전 증가는 위 규칙을 따릅니다.

사전 릴리스 (pre-release)

패치 번호 뒤에 하이픈(-)을 붙이고, 점(.)으로 구분된 식별자를 나열합니다.

• 식별자는 영숫자와 하이픈([0-9A-Za-z-])만 허용, 빈 식별자 불가
• 숫자 식별자는 선행 0 금지 (alpha.01 ❌ → alpha.1 ⭕)
• 수정카운트는 점 구분 숫자 식별자로 표기합니다 (alpha2 ❌ → alpha.2 ⭕)
• 사전 릴리스 버전은 동일한 일반 버전보다 우선순위가 낮습니다 (1.0.0-rc.1 < 1.0.0)

상태코드

• alpha — 내부 개발 테스트 버전
• beta — 개발 최종 완성 전 검증 버전
• rc (release candidate) — 베타보다 한 단계 개선된 버전. 실제 환경에 배포하여 rc.1 -> rc.2 -> rc.3 과정을 거친 후 최종 배포
• final release — 최종 배포 버전. 상태코드를 생략하며, 필요에 따라 stable 표기(stable 버전 브랜치 생성)

우선순위 비교 규칙

• 숫자 식별자는 수치로, 문자 식별자는 ASCII 사전순으로 비교합니다.
• 숫자 식별자 < 문자 식별자, 식별자 수가 적은 쪽 < 많은 쪽 (앞부분이 동일할 때)

1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta.1 < 1.0.0-beta.2 < 1.0.0-rc.1 < 1.0.0

빌드 메타데이터 (optional)

• 패치 번호 또는 사전 릴리스 뒤에 +를 붙여 표기합니다.
• 우선순위 비교에서 무시됩니다. (1.0.0+build.1과 1.0.0+build.2는 동일한 우선순위)

1.0.0+20260716
1.0.0-beta.1+exp.sha.5114f85

버전 표기 시나리오

# 프로젝트 시작
v0.1.0-alpha.1  (iteration 1 종료)
v0.1.0-alpha.2  (iteration 2 종료)
v0.1.0-alpha.3  (iteration 3 종료)
# 베타 테스트 시작
v0.1.0-beta.1   (latest alpha)
v0.1.0-beta.2   (bug fix)
# 배포 전 버전 검증 시작
v0.1.0-rc.1     (latest beta)
v0.1.0-rc.2
# 배포
v0.1.0

참고: v 접두사는 SemVer 스펙에 포함되지 않는 git 태그 관습입니다. 버전 문자열 자체는 0.1.0-rc.1이며, 태그명으로 v0.1.0-rc.1을 사용합니다.

thanks so much ~